claude-multi-teams

claude-multi-teams

Drives sibling AI CLIs (claude, later codex/gemini) running in mux panes:

• send: bracketed paste via tmux paste-buffer -p (real tmux) or tmux send-keys -l with raw ESC[200~ markers (cmux claude-teams shim) — both deliver multi-line + special chars atomically.
• receive: tail the agent's jsonl session file, wait for stop_reason, extract assistant text

When to use

Triggered by user requests like:

• "X 한테 시켜서 ..."
• "X 랑 토론해서 ..."
• "X 한테 검사받아"
• multi-agent workflows (parallel review, sequential pipeline, etc.)

Requirements

• A multiplexer environment: real tmux ($TMUX set) or cmux claude-teams (which sets a fake $TMUX + $CMUX_SOCKET_PATH so claude-multi-teams rides on top — see "Multiplexer support" below).
• Target CLIs installed: claude (Phase 1), codex/gemini (Phase 3).
• jq available.

Multiplexer support

claude-multi-teams works in two environments transparently:

Environment	How
Real tmux session	Native: claude-multi-teams calls tmux paste-buffer -p, tmux split-window, etc. against the actual tmux server.
cmux terminal	Launch your primary Claude Code via cmux claude-teams (cmux ships a tmux shim that translates the tmux CLI into cmux's surface API). claude-multi-teams's mux_paste_bracketed detects $CMUX_SOCKET_PATH and uses send-keys -l with raw ESC[200~…ESC[201~ markers since the shim has no paste-buffer subsystem.

For users with a separate Claude config (e.g. claude-spare alias = CLAUDE_CONFIG_DIR=$HOME/.claude-spare claude), launch cmux claude-teams with the env var set so claude-multi-teams-spawned sub-agents share the same config:

CLAUDE_CONFIG_DIR=$HOME/.claude-spare cmux claude-teams

claude-multi-teams's spawn.sh propagates CLAUDE_* / ANTHROPIC_* to every spawned worker, so each sub-agent inherits the parent's config dir automatically.

Out of scope: plain claude invoked inside cmux without cmux claude-teams. cmux's default pty env lacks $CMUX_PANE / $CMUX_WORKSPACE_ID, so claude-multi-teams cannot identify its own pane to split from. Use cmux claude-teams.

Commands

SKILL=~/.claude/skills/claude-multi-teams/scripts

# Spawn an agent in a new tmux split. Optional --task sends an initial prompt.
bash $SKILL/spawn.sh <agent> <name> [--task "first prompt"]
                                     [--cwd <dir>] [--permission-mode <mode>] [--model <m>]
  # agent: claude | codex   (gemini not yet implemented)

# Hub-and-spoke: send prompt, block until done, print response on stdout.
bash $SKILL/ask.sh [--timeout S] <name> "prompt"
bash $SKILL/ask.sh [--timeout S] <name> @/path/to/prompt-file.txt
cat prompt.txt | bash $SKILL/ask.sh [--timeout S] <name> -
# Default timeout: 600s wall-clock OR ALPHAFORK_IDLE_MAX (default 120s) of
# no jsonl growth (lets long thinking-heavy turns succeed). Per-call override
# via --timeout. Exit codes: 0 ok, 1 error, 1 + status=timeout for time limits.

# Invoke a slash command (skill) in a spawned agent. Use this whenever you
# want the agent to dispatch its own skill (/grill-me, /code-review, etc.) —
# see "Invoking a skill" below for why a hand-written prompt does NOT work.
bash $SKILL/ask-skill.sh <name> <skill> [args]
bash $SKILL/ask-skill.sh <name> <skill> @/path/to/args.txt

# Recover the last assistant reply from an agent's session jsonl. Useful when
# ask.sh aborted/timed out but the agent actually finished after.
bash $SKILL/last-reply.sh <name>

# P2P: drive a multi-agent discussion. Participants exchange messages via
# @<name>: until one of them emits [CONSENSUS: ...] or [DEADLOCK: ...]. Result
# (verdict + full transcript) printed on stdout.
bash $SKILL/ask-group.sh <name1,name2,...> "<topic>" [--max-turns N] [--per-ask-timeout S]

# Work-then-review: one impl agent produces; N reviewers review in parallel.
# If any reviewer asks for changes, impl iterates. Loops until all approve, any
# reject, impl gives up, or --max-rounds is hit.
bash $SKILL/review.sh <impl> <reviewer1,reviewer2,...> "<task>"
                                                       [--max-rounds N] [--per-ask-timeout S]

# Render the call tree from flow.log (passive observer). See "flow.log" below.
bash $SKILL/viewer.sh                  # tree with status badges
bash $SKILL/viewer.sh --excerpts       # also show prompt/reply previews

# List currently-tracked agents.
bash $SKILL/list.sh

# Close a pane and forget the agent.
bash $SKILL/kill.sh <name>
bash $SKILL/kill.sh --all

Invoking a skill (slash command) in a spawned agent

READ THIS BEFORE WRITING A PROMPT THAT NAMES A SKILL.

Spawned claude / codex CLIs dispatch a skill only when the prompt literally starts with /<skill-name>. They do not pattern-match on natural language. So if you want the agent to actually run /grill-me, the prompt sent to its pane MUST be:

/grill-me <topic>

If you instead write:

You are running the /grill-me skill on topic X. Ask 10 sharp questions about...

→ the agent receives that as a long string of instructions and proceeds to imitate what it thinks the skill does. The actual skill never runs. You get your hand-written paraphrase, not the real procedure. This is a silent failure: output looks plausible but isn't the skill's output.

Right way

SKILL=~/.claude/skills/claude-multi-teams/scripts
bash $SKILL/spawn.sh claude grill-reviewer
bash $SKILL/spawn.sh claude code-reviewer
bash $SKILL/spawn.sh codex  codex-reviewer

# These dispatch the actual skills inside each agent:
bash $SKILL/ask-skill.sh grill-reviewer  grill-me     "PRD for X — find every weak assumption"
bash $SKILL/ask-skill.sh code-reviewer   code-review  high

# codex has no slash commands, so it gets a natural-language prompt — that's
# fine FOR codex because there's no skill to dispatch in the first place:
bash $SKILL/ask.sh codex-reviewer @/tmp/codex-prompt.txt

Wrong way (silent failure)

# DON'T: writing a long prompt that names the skill but doesn't invoke it.
bash $SKILL/ask.sh grill-reviewer "You are running /grill-me. Walk each branch..."
# The agent receives instructions, NOT a skill dispatch.

The wrapper

ask-skill.sh exists to make the right shape impossible to get wrong:

• Constructs /<skill> <args> and forwards to ask.sh.
• Validates the skill name (rejects leading /, rejects shell metachars).
• Accepts @file for long args, or stdin via -.
• Passes through --timeout S to ask.sh.

If you find yourself writing more than one line of "this is what the skill does", stop and use ask-skill.sh instead.

When this matters most

• Running cross-agent reviews (/grill-me, /code-review, /security-review, etc.) where the skill's procedure is what makes the review valuable.
• Multi-angle reviews where each reviewer should apply a different skill's procedure — paraphrasing collapses them to the same shape.
• Anything where the skill name appears in user-facing output ("we ran /code-review" — but actually you ran your imitation of it).

Example: get a second opinion from another claude

SKILL=~/.claude/skills/claude-multi-teams/scripts
bash $SKILL/spawn.sh claude reviewer
git diff > /tmp/diff.txt
{
  echo "Review this diff and report issues. Be concise."
  echo "----"
  cat /tmp/diff.txt
} > /tmp/prompt.txt
response=$(bash $SKILL/ask.sh reviewer @/tmp/prompt.txt)
echo "$response"
bash $SKILL/kill.sh reviewer

Example: P2P discussion (two agents debate, harness captures the verdict)

SKILL=~/.claude/skills/claude-multi-teams/scripts
bash $SKILL/spawn.sh claude alice
bash $SKILL/spawn.sh codex bob
verdict=$(bash $SKILL/ask-group.sh alice,bob \
  "Discuss: should a function reading a file be named read_file, read_file_contents,
   or load_file? Pick ONE and emit [CONSENSUS] within 2-3 short exchanges.")
echo "$verdict"   # → [CONSENSUS] [CONSENSUS: Use read_file ...]  (+ transcript)
bash $SKILL/kill.sh --all

Example: work-then-review (codex implements, claude reviews)

SKILL=~/.claude/skills/claude-multi-teams/scripts
bash $SKILL/spawn.sh codex  worker
bash $SKILL/spawn.sh claude reviewer
verdict=$(bash $SKILL/review.sh worker reviewer \
  "Write a bash function `slug_of` that turns a string into a kebab-case slug:
   lowercase, ASCII-only, runs of non-alnum collapse to single '-', strip
   leading/trailing '-'. Print the function definition only.")
echo "$verdict"   # → [APPROVED] all reviewers approved at round 1  (+ artifact + transcript)
bash $SKILL/kill.sh --all

review.sh protocol (sentinels)

Reviewer replies must contain ONE of:

• [APPROVE] — work is acceptable
• [CHANGES_REQUESTED: <numbered list>] — concrete, actionable issues
• [REJECT: <reason>] — fundamentally wrong, not fixable by iteration

Impl, on iteration, may emit [GIVE_UP: <reason>] instead of a revised artifact.

The harness terminates when: all reviewers [APPROVE], any reviewer [REJECT]s, impl [GIVE_UP]s, or --max-rounds is hit.

P2P discussion protocol (injected into each participant's system prefix)

You are participating as "<your-name>". Other participants: <list>.
- Address one participant:  @<name>: <message>     (one mention per line)
- Broadcast to everyone:    @all: <message>
- Group agreement reached:  [CONSENSUS: <one-line summary>]
- Cannot agree:             [DEADLOCK: <reason>]

If a participant would only express agreement with no new concern, it must emit [CONSENSUS: ...] instead of natural-language agreement; any remaining concern or edge case should be voiced first.

The harness:

• sends the topic to all participants in parallel as the initial round
• parses each reply for @<name>: mentions → batches per recipient → dispatches in parallel next turn
• terminates as soon as any participant emits [CONSENSUS:...] or [DEADLOCK:...]
• terminates with DEADLOCK if a turn produces zero mentions (discussion stalled)
• terminates with MAX_TURNS verdict after --max-turns turns (default 8)

State

• Agent metadata: ~/.cache/claude-multi-teams/agents/<name>.json
  • {name, agent, pane_id, session_file, started_at}
• Override location with ALPHAFORK_STATE_DIR.
• Override per-call wall-clock timeout with ALPHAFORK_TIMEOUT (default 600s) or --timeout S flag.
• Override per-call idle ceiling with ALPHAFORK_IDLE_MAX (default 120s of no jsonl growth → 124).

flow.log — shared observability substrate

Every ask.sh invocation appends two jsonl events to ~/.cache/claude-multi-teams/flow.log (override with ALPHAFORK_LOG):

{"ts":"…","event":"pending","call_id":"c…","parent_call_id":"c…","depth":N,"from":"…","to":"…","prompt_excerpt":"…"}
{"ts":"…","event":"done","call_id":"c…","duration_ms":N,"status":"ok|error|aborted|timeout","reply_excerpt":"…"}

• from is detected automatically from $TMUX_PANE → agents/*.json lookup. Agents call ask.sh <other> "..." exactly the same way; they don't need to know their own name. Calls from outside any tracked pane log from="parent" (in-tmux) or "external" (no tmux).
• parent_call_id is the most recent unmatched pending where to=<caller> — i.e., the call the caller is currently servicing. Top-level calls have parent_call_id=null.
• prompt_excerpt/reply_excerpt are whitespace-collapsed previews capped at ALPHAFORK_EXCERPT_MAX chars (default 200).
• Append is atomic under PIPE_BUF (~4KB); no flock needed.
• flow.log is shared: parent uses viewer.sh (tree); children can cat $ALPHAFORK_LOG or run viewer.sh from their own Bash tool. Same source of truth, different views.
• Passive observer: nothing enforces depth/cycle/budget. If you want enforcement, that's an explicit promotion — not built in.
• Lifecycle: append-only forever. Truncate manually with : > ~/.cache/claude-multi-teams/flow.log when you want a fresh slate.
• Robustness: ask.sh traps EXIT, so a killed/crashed process still logs done with status="aborted" — no phantom "in-flight" entries. Malformed lines are tolerated by find_my_active_parent / depth_of_parent / viewer.sh (skipped silently).
• Status values: ok (terminal stop_reason), timeout (adapter exit 124 = hard ceiling or ALPHAFORK_IDLE_MAX exhausted), aborted (process killed before done was logged), error (anything else).
• In-flight view in viewer.sh: pending entries get a liveness badge from the target agent's session jsonl mtime: ▶active (< 5s ago), ▶idleNs/m/h/d, or ⏰stale (pending older than --stale-after).

Status

• ✅ Patterns shipped: ask.sh (hub-and-spoke), ask-group.sh (N-way P2P discussion), review.sh (work-then-review with N reviewers + iteration)
• ✅ Adapters: claude (via --session-id), codex (snapshot-diff + trust override + long-paste file-handoff)
• ✅ Observability: flow.log + viewer.sh tree (passive — no enforcement)
• ⏳ gemini adapter — not yet implemented (jsonl format varies across versions)
• ⏳ Known limits — agent protocol compliance is imperfect (~50% reliability on @<other>: addressing); no automatic self-mention correction yet