NousResearch Claude Code Orchestration
Run Claude Code as a controlled subagent. Useful for isolated tasks that need their own context window, or to parallelize across multiple sessions.
Trigger phrases: "run claude code", "spawn claude", "delegate to claude code", "claude -p", "orchestrate claude", "claude subagent"
Mode 1 — Print Mode (One-Shot)
Best for: self-contained tasks, CI-like execution.
# Basic one-shot
terminal(command="""
claude -p 'Add input validation to src/api/users.ts' \
--allowedTools 'Read,Edit,Bash' \
--max-turns 15 \
--output-format text
""")
# With multi-line context
terminal(command="""
claude -p "$(cat <<'PROMPT'
Context: Fixing auth bug described in ISSUE.md.
Task: Fix JWT expiry check in src/auth/verify.ts.
Verify: Run npm test -- --testPathPattern=auth and confirm all pass.
PROMPT
)" --allowedTools 'Read,Edit,Bash' --max-turns 20
""")
Key flags:
| Flag | Use |
|---|---|
--allowedTools 'Read,Edit,Bash' |
Restrict tools |
--max-turns 15 |
Hard stop |
--output-format text |
Clean output |
--no-permission-prompts |
Auto-deny prompts (safe for subagents) |
Mode 2 — PTY/tmux (Interactive Multi-Turn)
Best for: complex tasks requiring follow-up instructions.
# Start session
terminal(command="tmux new-session -d -s claude-work -x 220 -y 50")
terminal(command="tmux send-keys -t claude-work 'cd /workspace && claude' Enter")
terminal(command="sleep 3 && tmux capture-pane -t claude-work -p | tail -5")
# Send task
terminal(command="tmux send-keys -t claude-work 'Refactor src/auth/ to use new JWT library.' Enter")
# Monitor
terminal(command="sleep 30 && tmux capture-pane -t claude-work -p | tail -20")
# Follow-up
terminal(command="tmux send-keys -t claude-work 'Also update db/migrations/002_auth.sql' Enter")
# Collect + clean up
terminal(command="tmux capture-pane -t claude-work -p")
terminal(command="tmux kill-session -t claude-work")
Parallel Sessions
tasks = ["Fix auth", "Add tests", "Update docs"]
for i, task in enumerate(tasks):
terminal(command=f"tmux new-session -d -s work-{i}")
terminal(command=f"tmux send-keys -t work-{i} 'claude' Enter")
terminal(command=f"tmux send-keys -t work-{i} '{task}' Enter")
# Collect all results
for i in range(len(tasks)):
terminal(command=f"tmux capture-pane -t work-{i} -p | tail -10")
terminal(command=f"tmux kill-session -t work-{i}")
Tool Restriction by Task Type
| Task | --allowedTools |
|---|---|
| Code review | Read,Grep,Glob |
| Bug fix | Read,Edit,Bash |
| New feature | Read,Write,Edit,Bash |
| Docs update | Read,Write,Edit |
Always exclude WebFetch,WebSearch unless needed.
Anti-Fake-Pass
❌ No --max-turns → session runs forever
❌ tmux mode for simple one-shot → use print mode
❌ Not cleaning up tmux sessions → resource leak
❌ Sending next instruction before previous completes
❌ Not capturing output → can't verify what claude did
See Also
core/skills/claude-swarm-orchestration/SKILL.md— Python swarm with quality gatecore/agents/spec-executor.md— plan execution agent