agent-spawnkit

Why burn your most expensive agent's tokens on small tasks?

Let your premium agent (Claude Opus, GPT-5, whatever you're paying top rates for) delegate the grunt work — boilerplate, renames, test scaffolding, routine edits, "go read these 20 files and summarize" — to cheaper agents across other providers, and keep its own context lean for the work that actually needs it.

agent-spawnkit is an MCP server that lets your AI coding agent spin up other AI agents as workers: hand off a task, keep the session alive, send follow-ups that retain full context, run several in parallel. Works with Claude Code, OpenCode, Codex, Cursor, Windsurf, Claude Desktop — any MCP client.

How it saves you tokens & money:

• 🧠 Your expensive orchestrator stays focused — workers do the busywork on their own dime.
• 💸 Route small/routine tasks to cheaper models or providers instead of paying top-tier rates for them.
• 🪶 Heavy context (long files, tool output, dead ends) stays in the worker — you get back a short distilled summary, not a bloated window.

⚡ Set up in 10 seconds

Claude Code — paste this in your terminal:

claude mcp add agent-spawnkit -- npx -y agent-spawnkit

Restart Claude Code. Done — it now has the spawn_* tools.

Any/all other CLIs — auto-detect and register everything installed:

npx agent-spawnkit init            # this project
npx agent-spawnkit init --global   # all projects

Requirements: Node ≥ 20, and at least one worker on your PATH — opencode, claude, or codex.

🤖 Or hand it to your agent

Don't want to read anything? Paste this to your coding agent and it does the rest:

Set up agent-spawnkit so you can delegate work to sub-agents.

1. Run claude mcp add agent-spawnkit -- npx -y agent-spawnkit (or npx agent-spawnkit init for other CLIs).
2. Tell me to restart you so the MCP server loads.
3. After I'm back, you'll have spawn_* tools. To use one: call spawn_open_session({ engine: "opencode", workdir: "<this project>" }) to get a task_id, then spawn_send({ task_id, prompt: "<the task>" }). Sync returns the result directly. Send follow-ups to the same task_id — the worker keeps full context. Use isolate: true only if you run several workers editing the same files. Read the tool descriptions for the rest.

✅ Try it

After setup, just ask your agent in plain English:

"Open an opencode sub-agent and have it create a hello.py that prints hi."

It calls spawn_open_session + spawn_send, the worker does it, and it reports back. Then:

"Now have it add a --name argument."

Same session, full context — no restating.

What you get

Your agent ──MCP──► agent-spawnkit ──HTTP──► opencode serve
             (orchestrator)  (this package)  └─subprocess─► claude -p · codex exec

• Stateful sessions — follow-ups to the same task_id continue the same worker with full context. No re-sending history.
• Parallel workers — run several at once, each optionally isolated in its own git worktree.
• Any-to-any — the orchestrator and worker can be different engines (Claude driving OpenCode, etc.).
• Zero repo pollution — no config files written into your project; workers run headless.

Tools

| Tool | Purpose | |------|---------| | spawn_open_session | Open a worker session. Returns a task_id. | | spawn_send | Send a prompt. Sync (default) blocks up to 60s and returns the result; async returns immediately. | | spawn_check | Poll a task's status: idle · running · done · error. | | spawn_result | Get the full result of a completed task. | | spawn_list_sessions | List all sessions — survives restarts. | | spawn_abort | Abort a running session. | | spawn_close_session | Close/delete a session; tears down its worktree & server. | | spawn_plan_set / _get / _clear | Write / read / delete a multi-agent plan (goal + per-agent responsibility & worktree flag). |

You rarely call these by hand — you ask your agent in plain English and it picks the right tools. The descriptions are self-documenting.

A few things worth knowing

Sync vs async. Sync spawn_send blocks up to 60s and hands you the result — best for quick tasks. Longer work returns { status: "running" }; keep working and call spawn_check later. Nothing pushes into your agent's chat when a task finishes (MCP can't wake a turn) — a desktop notification pings you on async completion, and you ask the agent to fetch the result.

Worktrees are opt-in. Pass isolate: true only when multiple workers edit overlapping files at once — each gets its own git worktree + branch + server. Off by default. spawn_close_session({ delete: true }) cleans it all up.

Self-healing. If opencode auto-updates while its server keeps running, agent-spawnkit detects the stale binary and respawns a fresh one automatically.

Add .agent-spawnkit/ to your .gitignore — it holds the token, session registry, transcripts, and worktrees.

Install for other clients

{ "mcp": { "servers": { "agent-spawnkit": { "command": "/usr/local/bin/npx", "args": ["-y", "agent-spawnkit"] } } } }

[mcp.servers.agent-spawnkit]
command = "/usr/local/bin/npx"
args = ["-y", "agent-spawnkit"]

{
  "mcpServers": {
    "agent-spawnkit": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "agent-spawnkit"],
      "env": { "AGENT_SPAWNKIT_ROOT": "/absolute/path/to/your/project" }
    }
  }
}

GUI clients don't inherit your shell PATH or cwd — use the absolute path to npx (which npx) and set AGENT_SPAWNKIT_ROOT to your project.

Engines

| Engine | Orchestrator | Worker | Session mechanism | |--------|:---:|:---:|---| | Claude Code | ✅ | ✅ | claude -p --session-id/--resume, headless permission bypass | | OpenCode | ✅ | ✅ | local HTTP session API (auto-spawned opencode serve) | | Codex | ✅ | ✅ | codex exec --session |

Configuration (optional)

Three layers, later wins: ~/.agent-spawnkit/config.json → project .agent-spawnkit/config.json → tool-call params. All fields optional:

{
  "opencodePort": 4096,
  "defaultTimeoutSec": 60,
  "defaultEngine": "opencode",
  "notifyOnComplete": true,
  "permissions": { "edit": "allow", "bash": "allow", "webfetch": "deny" }
}

• opencodePort is just a preferred port. If it's already taken (another project's server, or unrelated software), agent-spawnkit transparently picks a free port instead — you never get a hard "port in use" failure. Each project gets its own server on its own port, tracked in ~/.agent-spawnkit/servers.json.
• Project config is inherited by subdirectories — the nearest .agent-spawnkit/config.json up the tree applies, so opening a session in a subfolder still sees your project settings.

Managing servers:

agent-spawnkit stop     # kill all opencode servers agent-spawnkit started

Security & files

• opencode server binds to 127.0.0.1 only, protected by a random token at ~/.agent-spawnkit/token (mode 0600), shared across your projects so servers can authenticate each other.
• Recursion guard (AGENT_SPAWNKIT_DEPTH) stops a worker from spawning further workers.
• Secrets matching KEY=value are redacted from stored transcripts.
• Workers run headless and auto-approve tool use (no human to answer prompts) — run agent-spawnkit only in projects you trust it to edit.
• Per-project state (session registry, transcripts, worktrees) lives in .agent-spawnkit/ in each project. npx agent-spawnkit init auto-adds it to your .gitignore; add it yourself if you register manually.

For agent authors

See docs/ORCHESTRATION.md — a snippet to paste into your CLAUDE.md / AGENTS.md that teaches an orchestrating agent the workflow rules.

Development

npm install && npm run build && npm test

License

MIT