How it works

• Detect. Auto-finds 86 frameworks across 14 ecosystems — Next.js, Vite, Remix, Rails, Django, FastAPI, Go, Cargo, Turborepo, pnpm workspaces. No YAML required.
• Pick. Interactive selector on first run. Arrow keys to choose which processes to start, Enter to confirm. Saved for next time.
• Run. Daemon-backed processes that survive the UI. Close the terminal, reattach later — everything keeps running.
• Heal. Stale node_modules? Detected and reinstalled. Port 3000 held by yesterday's zombie? Found, surfaced, and killed.

What it replaces

• Five terminal tabs. One TUI with a process grid, log viewer, search, and click-to-copy.
• docker-compose for dev. Native processes, faster startup, same interface for local-first workflows.
• Manual log tailing. stackplay search "error" hits every process at once. trace "payment" merge-sorts a cross-process timeline.
• Stale-port guessing. stackplay ports :3000 shows the holder, dead or alive, with no daemon required.
• Silent agent hangs. stackplay watch --ndjson streams typed lifecycle events so a crash shows up as proc.stopped instead of an indefinite wait.

Commands

Inspection commands and mutation results are JSON-first. Bounded reads keep agent loops from hanging. Full reference in docs/cli.md.

• $stackplay—daemon + TUI in one go
• $sp—same, fewer keystrokes
• $stackplay up --json—headless, structured result
• $stackplay ps --json—status, ports, errors, uptime
• $stackplay health --json—ok/issues verdict for the whole stack
• $stackplay logs api --no-follow --json—bounded read that won't hang a loop
• $stackplay search "error" --json—search every process at once
• $stackplay trace "payment" --json—merge-sorted cross-process timeline
• $stackplay ports :3000 --json—listening ports, daemon optional
• $stackplay watch --ndjson—typed lifecycle + log events for agents
• $stackplay mark api needs-input—agent-visible process annotations
• $stackplay hooks approve --all—trust project lifecycle hooks locally
• $stackplay restart api --dry-run --json—preview a restart, get a structured result

Configuration is optional

stackplay auto-detects most projects, but you can check in a stackplay.yaml for a stable, shared process contract on your team.

stackplay.yamlprocs:
  api:
    shell: "npm run dev"
    cwd: "./services/api"
    env:
      PORT: "4000"
    autorestart: true
    ports: [4000]

  web:
    shell: "npm run dev"
    cwd: "./apps/web"
    deps: [api]
    ports: [3000]

settings:
  scrollback: 20000
  theme: midnight

hooks:
  pre-start:
    api: "scripts/check-env.sh"
  on-fail:
    api: "scripts/capture-failure.sh"

Made for AI agents

• JSON-first. Every inspection command supports --json or --ndjson. Mutations return structured results too — start, stop, restart, send, add, remove.
• Bounded by default. logs --no-follow won't hang a tool loop, search --max-hits caps result size.
• Push-based events. stackplay watch emits typed lifecycle events — a crash shows up as proc.stopped with an exit code, not silence.
• Visible handoffs. stackplay mark api investigating puts agent state in ps, health, and the TUI.
• Approved hooks. Checked-in lifecycle hooks require first-run user approval before project commands execute locally.
• Self-describing. stackplay describe ps --json returns machine-readable command metadata for tool discovery.

Install the agent skill into Claude Code, Cursor, Codex, opencode, Aider, Windsurf:

Homebrew

Prefer Homebrew on macOS or Linux? Tap the formula and install:

macOS & Linux on arm64 / amd64. Both methods drop stackplay and the sp shorthand on your $PATH. Source and signed releases on GitHub. Windows is on the roadmap.

Frequently asked