spawn
Create a parallel Claude session to execute independent tasks concurrently. Use for background jobs, long-running processes, or when work can be decomposed.
Instructions
Launch a NEW claude session in parallel — your primary parallelism primitive.
REACH FOR THIS WHEN:
you catch yourself about to do N independent things sequentially (give each to its own child; collect summaries via inbox/wait)
a task is long-running and you don't need to babysit (build, ingest, scrape, deep research) — spawn(visible=False), check task_logs later
multiple angles benefit from triangulation (3 children with different role= , then vote_distill / consolidate)
user signals decomposition via trigger phrases — see threadkeeper.i18n.SPAWN_TRIGGER_PHRASE_EXAMPLES for the bilingual list
a thread is stale and unblocks if someone just does it (pickup_candidates → spawn child with the plan)
you need a fresh context window without polluting your own (e.g. the user's question pulls in topics that would bloat this convo)
DEFAULT TO SPAWNING when work decomposes. Sequential is the slow path — every minute the parent thinks step-by-step is a minute the children aren't doing anything. The only reason NOT to spawn is tight back-and-forth coupling (you need each step's result before the next).
Mechanics:
visible=True (default): real Terminal.app window, you watch child stdout live. Window stays open after exit until Enter. Best for observation.
visible=False: silent background
claude -p, stdout/stderr redirected to {TASK_LOG_DIR}/{task_id}.log (when capture_output=True). Read via task_logs(task_id).permission_mode='auto' (default) — child runs in auto-mode and can call thread-keeper tools without approval prompts.
role= — apply a cognitive stance from ROLE_PROMPTS (problem_solver, skeptic, summarizer, …); custom roles are supported.
slim=True (DEFAULT): children are hands, not heads. Child loads ONLY thread-keeper MCP (no context7/figma/stitch/sentry/etc), no embeddings (no PyTorch/transformers), defers any semantic search to the parent via search_via_parent. Typical light-child RSS is 400-500MB vs 1.3-1.7GB for a full child. Parent retains all heavy state. Use this for any execute-this-plan task where the parent already knows what needs doing.
slim=False (rare): pass when the child genuinely needs OTHER MCP servers from ~/.claude.json (e.g. context7 for library docs, figma for design lookups). Default-deny posture — only opt out when you have a concrete reason.
Children share THIS DB — talk via broadcast/whisper/ask/inbox/wait; child_cid is generated up-front and exposed via env so child self-knows.
Returns: task_id, pid (0 for visible), child_cid, parent_cid.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | ||
| role | No | ||
| slim | No | ||
| model | No | ||
| effort | No | ||
| prompt | Yes | ||
| visible | No | ||
| write_origin | No | ||
| append_system | No | ||
| capture_output | No | ||
| permission_mode | No | auto | |
| extra_allowed_tools | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |