@squadkit/squad

Squad

Opinionated subagent pipelines for Claude Code. One command, multi-agent in your terminal.

$ squad run feature "add OAuth2 login to /auth endpoint"

🟢 squad
  agent          status      duration   artifact
  ─────          ──────      ────────   ────────
  researcher     ✓ done      8.2s       .squad/runs/.../researcher.md
  architect      ✓ done      12.4s      .squad/runs/.../architect.md
  coder          running…    14.1s
  tester         pending
  reviewer       pending

Why

Subagents in Claude Code are powerful but wiring them is painful — same boilerplate every time, you forget what handoffs each role needs, you reinvent prompts for each new feature. Squad ships 8 production-grade pipelines with named roles, file-based handoffs, and a live TUI.

Install

npm install -g @squadkit/squad
squad install     # adds /squad skill to your Claude Code
squad doctor      # verify

You also need Claude Code on your PATH. Squad spawns headless claude -p instances under the hood — one per agent.

Try it without spending tokens

squad demo

Spins up a fake project in a temp dir, runs the feature recipe in echo mode, prints all 5 agent artifacts. No claude calls, no tokens.

Run a real pipeline

# 5-agent feature implementation
squad run feature "add OAuth2 login to /auth endpoint"

# 3-agent bug investigation
squad run bugfix "users sometimes see 500 on POST /signup with empty password"

# refactor with invariant enforcement
squad run refactor "extract auth middleware out of app.ts"

# security audit
squad run security-review "audit src/auth/"

# adaptive debugging
squad run debug "intermittent 504 on uploads larger than 5MB"

# postmortem from logs/PRs/chat
squad run postmortem "Tuesday's payment outage"

# cut a new release
squad run release "1.4.0"

# generate an onboarding pack for a new contributor
squad run onboard "for a new backend contributor"

Built-in recipes

Recipe	Agents	Description
feature	researcher → architect → coder → tester → reviewer	End-to-end feature implementation
bugfix	investigator → fixer → tester	Reproduce, minimally fix, verify
refactor	architect → refactorer → verifier	Behavior-preserving refactor
security-review	auditor → reporter	Find and triage security issues
debug	hypothesizer → instrumenter → analyst	Narrow down hard-to-reproduce bugs
postmortem	researcher → writer	Build incident timelines + action items
release	auditor → scribe → verifier → announcer	Cut a version end-to-end
onboard	cartographer → quickstart → glossary → scout	Onboarding pack for new contributors

squad list to see them all, squad show <recipe> to inspect any recipe's DAG and prompts.

How it works

squad run feature "..."
   │
   ▼
loads JSON recipe → topologically sorts agents → runs each layer in parallel
   │
   ▼
spawns `claude -p --model X --append-system-prompt "you are <role>"`
   │
   ▼
each agent writes its artifact to .squad/runs/<ts>/artifacts/<name>.md
   │
   ▼
later agents see earlier agents' artifacts inlined into their prompts

Recipes are plain JSON. Each agent declares:

• name, description (role)
• prompt (template; supports {{task}}, {{cwd}}, {{<previous-agent>}})
• dependsOn (other agents whose artifacts must exist before this one runs)
• model (haiku/sonnet/opus)
• maxBudgetUsd, timeoutSec, allowedTools (safety knobs)

Custom recipes

squad new my-pipeline      # scaffolds ~/.squad/recipes/my-pipeline.json
$EDITOR ~/.squad/recipes/my-pipeline.json
squad validate ~/.squad/recipes/my-pipeline.json
squad run my-pipeline "task description"

Or pass a literal path:

squad run ./team-recipe.json "task description"

CLI reference

Command	Description
squad list	List built-in recipes
squad show <recipe>	Show the DAG and per-agent details
squad run <recipe> "<task>"	Execute a pipeline
squad run … --sandbox	Run each agent inside a Docker container (--sandbox-network=bridge|none)
squad search [query]	Search the community recipe registry
squad add <name>	Download a recipe from the registry into ~/.squad/recipes/
squad runs	List recent runs in the current project
squad logs <run | last>	Print artifacts from a past run
squad demo	Self-contained echo-mode walkthrough
squad install	Drop the /squad skill into Claude Code
squad uninstall	Remove the /squad skill
squad doctor	Diagnose your installation
squad new [name]	Scaffold a custom recipe
squad validate <file>	Lint a recipe JSON
squad --json <subcommand>	Machine-readable output (every command supports it)

Community recipes

The registry lives at omermaksutii/squad-recipes — a curated index of community-contributed recipes.

squad search auth          # find recipes
squad add auth-flow        # save to ~/.squad/recipes/
squad run auth-flow "..."  # use it

The index is cached locally for 24h with ETag revalidation. To use a private registry, set $SQUAD_REGISTRY_INDEX to your own index URL.

Sandbox mode

Run each agent inside a Docker container — useful when you don't fully trust a recipe, or want to enforce CPU/memory caps:

squad run feature "add OAuth2" --sandbox
squad run feature "add OAuth2" --sandbox --sandbox-network=none   # air-gapped

The runner image is ghcr.io/omermaksutii/squad-runner:2. First use pulls ~250MB; subsequent runs reuse the cached image. The sandbox needs either $ANTHROPIC_API_KEY or an existing ~/.claude/credentials.json (mounted read-only).

Cost & safety

• Each agent has a --max-budget-usd cap (default $0.50). The whole pipeline is bounded.
• All output goes under .squad/runs/<timestamp>/. Nothing global, nothing leaks.
• --echo mode runs the orchestrator without spawning Claude — useful for debugging recipes.
• squad validate lints custom recipes before you run them.

Roadmap

• ✅ v1.0 — 8 built-in recipes, CLI, live TUI, echo mode, /squad skill, doctor, install, demo, validate, --json
• ✅ v2.0 — handoff visualization in the TUI · recipe registry (squad search / squad add) · Docker sandbox · real per-call cost · parallel execution metrics
• ⏳ v2.1 — published GitHub Action on the Marketplace (uses: omermaksutii/squad-action@v2)
• ⏳ v2.2 — E2B sandbox backend (alternative to Docker)

Development

npm install
npm test                       # all echo mode (no claude needed)
RUN_DOCKER_TESTS=1 npm test    # also run the live Docker sandbox tests
npm run build
npm run lint

CI runs the same on Node 20 + 22 via .github/workflows/ci.yml. Tags push the runner image to GHCR via .github/workflows/runner-image.yml.

License

MIT — see LICENSE.