Run Claude Code, Codex and other agents side by side, coordinating through tmux-ide team groups, a shared status bus, direct messages and wait commands.

tmux-ide lets agents in different panes work as a team, even when they are different tools. A Claude Code lead can hand work to a Codex pane and wait for it to finish, using the same send, wait, events and team commands documented elsewhere.

Every agent is a process in a tmux pane, so coordination works with any agent. Claude Code reports its status through the integration hooks. Other agents report it with a one-line pane option, or the fallback detector recognizes them.

The coordination primitives

Systems / Agent coordination

Claude Code, Codex and opencode in one agent team.

~/project · agent-team● working! blocked✓ done○ idle

claudeOrchestrator%1
a. Coordination. Turns your goal into focused tasks and hands them to the team.
codexGoal agent%2↓ goal + acceptance criteria ↑ outcome + proof
b. Goal ownership. Owns one goal and asks specialists to resolve specific questions.
claudeResearch · A%3↓ scoped research tasks ↑ findings + recommendations
c. Parallel research. Each researcher works one bounded question in parallel.
opencodeResearch · B%4
Investigate APIs & documentation
codexResearch · C%5
Probe edge cases & validation options

tmux-idepersistent panessend · wait · read outputlive agent status

Fig 1.A goal goes to an execution agent, which splits bounded questions across three researchers; findings and the finished outcome flow back up for review.

Reading the figure. Each row is an agent process in its own pane; indentation shows who delegates to whom. Pairings are illustrative.

A shared status bus

Every agent publishes its state, and the whole fleet can read it. The fleet rollup is one JSON call, transitions stream as they happen, and any single pane's verdict is one command:

tmux-ide team --json               # fleet rollup: each session's + window's agent status
tmux-ide events --follow           # live stream of session-status transitions (JSONL)
tmux-ide agent explain %2 --json   # one pane's status (+ exactly why it was classified that way)

team --json includes a per-pane agents array; events reports session-level transitions. agent explain <pane> shows how one pane was classified.

Any agent joins the bus by self-reporting — no integration required:

tmux set-option -p @agent_state "working:$(date +%s)"   # working | blocked | done | idle

Claude Code does this automatically once you run tmux-ide integration install claude. For Codex, cursor-agent, or any other tool, either drop that one line into the agent's own lifecycle or rely on the fallback detector (process-tree + screen manifests). See Agent detection.

Send a task to another agent

tmux-ide send types a message straight into another agent's prompt — so agent A can hand agent B a task. Target a pane by ID (%2), title, role, or @ide_name:

tmux-ide send %2 "Implement POST /login per the spec in docs/auth.md, then run the tests"
tmux-ide send API --no-enter "draft: "        # stage text without submitting
echo "long instructions…" | tmux-ide send %2  # pipe from stdin

Messages over 150 characters are written to a dispatch file under .tasks/dispatch/ in the project, and the target is told to read it. That avoids paste-mode problems in agent interfaces.

send is the quick, human-style way to message an agent. When you need exact pane identity across servers, attributed senders and retry-safe handles, use agent automation instead.

Wait for a teammate

Block until a teammate reaches a state or produces output. Exit codes make it scriptable (0 = matched, 1 = timed out):

tmux-ide wait output %2 --match "tests passed" --timeout 300000   # wait on a pane
tmux-ide wait agent-status api --status done --timeout 600000     # wait on a session

See Wait for an agent in scripts for every option.

Inspect and isolate

tmux-ide agent explain %3     # why is the UI pane blocked? see exactly how it was classified
tmux-ide worktree create feature/login   # give a teammate an isolated checkout + session

Worked example: a Claude Code lead dispatching to Codex

Picture a Claude Code agent running as the lead in pane %0, with a Codex agent in %2. The lead can drive the whole loop from its own shell:

# 1. Read the fleet rollup, then check the codex pane specifically
tmux-ide team --json | jq '.projects[].sessions[] | {name, status}'
tmux-ide agent explain %2 --json | jq -r .classification

# 2. Hand the codex pane a task
tmux-ide send %2 "Add a /health endpoint returning {ok:true}, then run: npm test"

# 3. Block until codex reports the tests passing
tmux-ide wait output %2 --match "Tests:.*passed" --timeout 300000 \
  && echo "codex finished — reviewing its diff"

# 4. Re-read that pane's verdict before assigning the next task
tmux-ide agent explain %2 --json | jq -r .classification

Step 2 puts text into Codex's prompt exactly as if the lead had typed it. Step 3 watches Codex's own output. Steps 1 and 4 read the shared bus. None of it is Claude-specific — swap %2 for a cursor-agent or aider pane and the same commands hold. To wait on a whole session, such as a worktree running one agent, use tmux-ide wait agent-status <session> --status done instead of wait output.

The lead-agent pattern

The pattern that ties it together:

A lead — a human watching Home, or a lead agent — assigns work with send and worktrees.
Teammates report status (automatically for Claude Code, via the pane option for anything else).
The done/blocked state and its notification are the handoff signal: the lead reacts the moment a teammate finishes or gets stuck, instead of polling.

The status bus, messaging and waits are plain CLI commands with --json output and exit codes. Use the same pattern from scripts, a lead agent's tool calls or a Makefile.

A mixed fleet

In the app, Home and the sidebar list each agent with its state, and Attention (F7) jumps to the ones that need you. In a tmux chrome session the same fleet looks like this (illustrative):

 mixed-fleet   ●working                          [ ⌂ home ^b h ]  [ ⧉ switch ^b j ]
┌──────────────────────────────┬──────────────────────────────┐
│ Lead (claude)          %0    │ API (codex)            %2    │
│ claude · working   ●working  │ codex  · done      ●done     │
├──────────────────────────────┼──────────────────────────────┤
│ UI (cursor-agent)      %3    │ Shell                  %4    │
│ cursor · blocked   ●blocked  │ $                            │
└──────────────────────────────┴──────────────────────────────┘

One glance tells the lead (human or agent): the API agent is done, the UI agent is blocked and needs attention. That state is the handoff signal.

Group panes into a named team

A team is a presentation group of existing tmux panes. It can contain Claude, Codex, other agents, and supporting terminals. Grouping does not start an orchestrator or change how a harness manages its own teammates.

Assign existing panes on the same tmux server to a named group:

tmux-ide team assign %2 "Release crew" --json
tmux-ide team assign %5 "Release crew" --json
tmux-ide team unassign %5 --json

Use --socket-name NAME or --socket-path /absolute/socket to select another server explicitly. Run these commands on the machine that owns the panes. The same team name deliberately selects the same explicit group on that server; equal names on different machines or servers stay separate. These commands require exact pane IDs and do not send terminal input.

Home and the sidebar keep members together and display their team alongside the existing machine/session context. Home search also matches team names. A manual assignment takes precedence over discovered grouping. Removing it allows native team discovery to apply again. Member names still use the shared name resolver, including any manual pane-name override.

Assignments are pane-local: they survive moving a pane between windows or sessions and restarting the daemon. Replacing the pane process clears the assignment from the displayed inventory; assign the new process explicitly. Assignments do not restore deleted panes or join groups across machines.

Native Claude teams

Teammates from Claude Code agent teams that run in their own tmux panes are grouped automatically — see the next section.

Claude Code agent teams

With Claude Code agent teams, a Claude Code lead spawns Claude Code teammates, and in tmux each teammate gets its own split pane. tmux-ide shows those teammates by name, grouped under their team, with live status; see Claude Code agent teams for setup and limits.

Multi-agent teams