# tmux for agent fleets: sessions, send-keys, wait-for

URL: https://developertoolkit.ai/en/ecosystem/agent-tools/tmux-for-agent-fleets/
Description: Claude Code, Codex, and Cursor now create their own worktrees. What tmux still owns in a fleet: persistence, visibility, messages, and barriers.

tmux for agent fleets is the terminal-multiplexer layer around coding agents: it keeps sessions alive over SSH, shows which agent needs a human, and scripts messages and barriers between agents. Claude Code, Codex, and Cursor now create their own git worktrees, so tmux no longer owns file isolation. It owns persistence, visibility, and plumbing that works across different agents.

This page is for developers and tech leads who run three or more terminal agents at once, often on a remote box. The situation it fixes: five agents are running, one has sat on a permission prompt for 40 minutes, another finished and is waiting for a migration that landed an hour ago, and you closed your laptop on the way home.

## What you'll set up

- The built-ins to reach for first: `claude --worktree … --tmux`, split-pane agent teams, and cross-session messaging.
- A `bin/fleet` script that fans out N tasks without a single `git worktree` command.
- `send-keys`, `capture-pane`, and `wait-for` as the message, the poll, and the barrier, with the flags that stop each from failing silently.
- Hooks that turn "this agent is blocked" into an exact signal, and a verification gate so "done" means "tests pass", not "the agent stopped talking".

## What do Claude Code and Codex already do before you script tmux?

You need tmux 3.4 or later; every tmux behaviour on this page was checked on 3.4.

```bash
brew install tmux          # macOS
sudo apt install tmux      # Debian, Ubuntu
tmux -V                    # prints: tmux 3.4 (or later)
```

Check the built-ins first. Every flag below was checked against `claude --help` (Claude Code 2.1.283 on 2026-09-26, re-checked on 2.1.285) and `codex --help` (codex-cli 0.157.1).

**`claude --worktree NAME --tmux`** creates the worktree and opens it in its own tmux session. The help text: `--tmux` "Create a tmux session for the worktree (requires --worktree). Uses iTerm2 native panes when available; use `--tmux=classic` for traditional tmux."

```bash
# terminal, at the repo root
claude --worktree feature-auth --tmux           # iTerm2 panes when available, else tmux
claude --worktree feature-auth --tmux=classic   # always a plain tmux session
```

The worktree lands in `.claude/worktrees/feature-auth/` on branch `worktree-feature-auth`. If one session per task is all you need, stop here: this flag replaces most "worktree + tmux" scripts.

**Agent teams in split panes.** Agent teams are experimental and off by default; enable them with `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. The default display mode is `in-process`, where every teammate runs in your main terminal. To give each teammate its own pane, set `teammateMode` in `~/.claude/settings.json`:

```json
{
  "teammateMode": "auto"
}
```

`"auto"` uses split panes when you are already inside tmux, or in iTerm2 with the [`it2` CLI](https://github.com/mkusaka/it2) installed, and falls back to in-process otherwise. `"tmux"` forces split panes and detects tmux or iTerm2; `"iterm2"` forces iTerm2 panes and needs `it2` plus **iTerm2 → Settings → General → Magic → Enable Python API**. Split panes are not supported in VS Code's integrated terminal, Windows Terminal, or Ghostty ([agent teams docs](https://code.claude.com/docs/en/agent-teams)).

**Cross-session messaging.** From v2.1.224 on macOS, Linux and WSL 2 (v2.1.234 on native Windows), Claude Code sessions on one machine can message each other, and from v2.1.236 one session can ask another for a single notice when it next goes idle. For a Claude-only fleet this replaces most of the `send-keys` and `wait-for` plumbing below, with delivery between tool calls instead of keystrokes ([cross-session messaging docs](https://code.claude.com/docs/en/cross-session-messaging)).

**Codex** runs a session in a managed worktree with `codex --worktree` (also on `codex exec`), and `codex queue --thread THREAD --message TEXT` queues a message for an existing session, where `THREAD` is a session UUID or exact session name.

For the full comparison of built-ins, desktop apps, and third-party orchestrators, see [running agents in parallel](/en/ecosystem/agent-tools/parallel-agents/).

## Who owns what in an agent fleet?

| Concern | Owner | Why not the other one |
|---|---|---|
| **File isolation** | The agent | `claude --worktree`, `codex --worktree`, Cursor worktrees. Scripting it yourself duplicates a supported feature |
| **Runtime isolation** (ports, dev DB, container names) | **You** | Nobody does this for you. A worktree isolates files and nothing else |
| **Visibility** (which agent needs me) | tmux, or `claude agents` for Claude-only fleets | Status line and `choose-tree` see every agent; each agent sees itself |
| **Persistence** (close the lid, reattach over SSH) | tmux server | An agent dies with its terminal unless something outside it survives |
| **Messages between agents** | Claude Code messaging, `codex queue`; tmux for mixed fleets | tmux is the one channel that reaches Claude Code, Codex, and any other CLI agent alike |

**The runtime row is the one that bites.** Six agents in six worktrees all want port 3000, read the same `.env`, migrate the same dev database, and name their containers the same thing. Worktrees do not help. Fix it before you fan out: [alternative IDEs and agent shells](/en/ecosystem/agent-tools/agent-shells/) has a copy-paste audit prompt, and [sandboxes](/en/ecosystem/agent-tools/sandboxes/) covers container-per-agent isolation.

## How should you lay out tmux sessions for many agents?

Use one tmux session per task, not one pane per task. Panes work up to about three agents; after that they get too narrow to read a diff and you lose track of which is which. Sessions are *named*, so you jump to them by name. Inside each session, keep one window for the agent and one for the dev server or tests.

```bash
tmux switch-client -t =agent-auth-refresh   # jump by exact name
tmux choose-tree -Zs                        # browse the whole fleet as a tree
```

Put the fleet in your status line so "which agent needs me" is answerable without switching anywhere:

```bash
# ~/.tmux.conf
set -g status-left-length 80
set -g status-left '#{?client_prefix,#[reverse],}[#S] '
set -g status-right '#(tmux list-sessions -F "##{session_name}##{?session_attached,*,}" | tr "\n" " ")'
set -g status-interval 5
set -g history-limit 50000
```

Inside `#()`, double every inner `#`. tmux format-expands the command before it runs it, so a single `#{session_name}` becomes the current session's name and the status line repeats one name once per session.

For the base tmux layer (prefix, pane navigation, notifications), see [terminal mastery](/en/claude-code/build/terminal-mastery/).

## How do you fan out agent tasks with one tmux script?

`bin/fleet` creates one detached session per task and starts the agent inside it. Note what is missing: any `git worktree` call. The agent owns that.

```bash
#!/usr/bin/env bash
# bin/fleet -- one tmux session per task; the agent owns its own worktree
set -euo pipefail

[ $# -gt 0 ] || { echo "usage: FLEET_AGENT=claude|codex bin/fleet <slug> [slug...]" >&2; exit 1; }
agent="${FLEET_AGENT:-claude}"

for slug in "$@"; do
  # send-keys types into a shell, so a slug like 'x;id' would run `id`.
  case "$slug" in
    *[!a-zA-Z0-9._-]*|"") echo "invalid slug: $slug" >&2; exit 1 ;;
  esac

  case "$agent" in
    claude) cmd="claude --worktree $slug --name $slug" ;;
    codex)  cmd="codex --worktree" ;;
    *)      echo "unknown FLEET_AGENT: $agent" >&2; exit 1 ;;
  esac

  session="agent-$slug"
  # '=' forces an exact match; without it 'agent-api' matches 'agent-api-v2'
  if tmux has-session -t "=$session" 2>/dev/null; then
    echo "exists, skipping: $session" >&2
    continue
  fi

  tmux new-session -d -s "$session" -c "$PWD" -n agent
  tmux send-keys -t "=$session:agent" -l "$cmd"
  tmux send-keys -t "=$session:agent" C-m
  tmux new-window -d -t "=$session" -n run -c "$PWD"
done

first="=agent-$1"
if [ -n "${TMUX:-}" ]; then tmux switch-client -t "$first"; else tmux attach -t "$first"; fi
```

```bash
bin/fleet auth-refresh rate-limit-headers stripe-webhook-idempotency
```

What you should see in another terminal:

```console
$ tmux ls
agent-auth-refresh: 2 windows (created Sat Sep 26 10:02:11 2026)
agent-rate-limit-headers: 2 windows (created Sat Sep 26 10:02:11 2026)
agent-stripe-webhook-idempotency: 2 windows (created Sat Sep 26 10:02:11 2026)
```

Three sessions, three agents, three worktrees under `.claude/worktrees/`. The session you attached to also shows `(attached)`. `--name` also makes each Claude session addressable as `@auth-refresh` for cross-session messages.

**Two things fail the first time.** `claude --worktree` in an interactive run needs [workspace trust](https://code.claude.com/docs/en/security): if you have never run `claude` in that directory, the flag exits with an error. Run `claude` once, accept the dialog, then run the script. And a worktree is a fresh checkout without gitignored files, so list `.env` and friends in a `.worktreeinclude` at the repo root.

## How do you send a message to another agent with tmux send-keys?

`send-keys` types into a pane. The agent cannot tell that from you typing, which is why it works as a channel between different agents. Between two Claude Code sessions, prefer cross-session messaging; use `send-keys` when one side is Codex, another CLI agent, or a script.

```bash
tmux send-keys -t =agent-api:agent -l "The migration in agent-auth-refresh landed on main. Rebase and re-run the integration tests."
tmux send-keys -t =agent-api:agent C-m
```

- **`-l` sends the text literally.** Without it, tmux parses words such as `Enter` or `C-c` in your prose as key names.
- **Submit in a separate call.** `C-m` is a key name, so it cannot ride inside the `-l` argument.
- **Give the exact target a window.** `=` exact match needs a window part (`=name:` or `=name:window`) for pane commands such as `send-keys` and `capture-pane`; session commands (`has-session`, `attach`, `switch-client`) take `=name` alone. On tmux 3.4, `-t =agent-api` here fails with `can't find pane`.

**`-l` protects tmux's parser, not the receiving shell.** If the pane is at a shell prompt rather than inside the agent, everything you send becomes a command line after `C-m`. If an agent composes the text, you are piping model output into a shell. Validate it, or keep the channel to a fixed vocabulary you generate yourself. And never write blind into a pane that sits on a permission prompt: the first character answers it. Read the pane first.

## How do you poll an agent's state with capture-pane?

```bash
tmux capture-pane -p -J -t =agent-api:agent -S -200
```

`-p` prints to stdout. `-J` joins wrapped lines; without it a long path or stack frame is split at the terminal width and your `grep` misses it. `-S -200` starts 200 lines back in the scrollback.

A fallback supervisor built on it:

```bash
#!/usr/bin/env bash
# bin/agent-watch <session> -- report when a worker needs a human
set -euo pipefail
session="$1"
while tmux has-session -t "=$session" 2>/dev/null; do
  tail=$(tmux capture-pane -p -J -t "=$session:agent" -S -40)
  case "$tail" in
    *"Do you want"*|*"Allow "*|*"(y/n)"*) echo "BLOCKED $session"; break ;;
    *"error:"*|*"FAIL"*)                  echo "ERROR $session"; break ;;
  esac
  sleep 15
done
```

This is screen-scraping, and a new prompt wording breaks it. Hooks, below, are the mechanism; this loop is the fallback for agents without them.

## How do you make one agent wait for another with wait-for?

`wait-for` is a barrier: the waiting process blocks until something signals the channel. Channel names live on the tmux server, so any pane can signal any other with no shared files.

```bash
tmux wait-for -S migration-applied    # in the worker, after the step succeeded
```

```bash
tmux wait-for migration-applied       # in the orchestrator: blocks until signalled
tmux send-keys -t =agent-api:agent -l "Migration applied. Rebase onto main and re-run integration tests."
tmux send-keys -t =agent-api:agent C-m
```

On tmux 3.4, a signal sent before anyone waits is remembered once, so the next `wait-for` returns immediately. That saves a race, and it also means a stale signal from an earlier run releases a waiter early.

**Copy-paste prompt: fan-out and dependency plumbing**

```text
Read the task list below and generate two bash scripts.

1. bin/fleet: takes task slugs and creates one detached tmux session per
   slug named agent-<slug>, with windows "agent" and "run". The agent window
   runs `claude --worktree <slug> --name <slug>`. Do NOT call git worktree.
   Validate slugs against [a-zA-Z0-9._-], skip sessions that already exist,
   and use exact-match targets everywhere: -t "=agent-<slug>" for session commands
   and -t "=agent-<slug>:agent" for send-keys and capture-pane.

2. bin/fleet-deps: encodes the dependency order below with `tmux wait-for`.
   A dependent task waits on done-agent-<provider> for each provider, then
   runs the provider's test command in its worktree
   (.claude/worktrees/<provider>) and only prompts the dependent agent if the
   tests pass. Before writing to a pane, read it with `capture-pane -p -J` and
   refuse to send if it shows a permission prompt. Send prose with
   `send-keys -l` and submit with a separate C-m. Wrap every wait in
   `timeout 3600`.

Tasks and dependencies:
- db-migration          (no deps)            test: npm run test:db
- api-rate-limit        (after db-migration) test: npm run test:api
- webhook-idempotency   (after db-migration) test: npm run test:webhooks
- docs-update           (after api-rate-limit, webhook-idempotency)

Use `set -euo pipefail`, quote every variable, print a usage line with no
arguments, and add --dry-run that prints the tmux commands instead of running
them. Then run both scripts with --dry-run and show me the output.
```

## How do agent hooks replace screen-scraping?

Polling infers state from rendered text. Hooks invert it: the agent tells tmux what happened when it happens. In Claude Code, a `Stop` hook renames the window and signals a channel named after its own session; a `Notification` hook flags "I need you". Put this in `.claude/settings.json` (project) or `~/.claude/settings.json` (user):

```json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "S=$(tmux display-message -p -t \"$TMUX_PANE\" '#{session_name}' 2>/dev/null); tmux rename-window -t \"$TMUX_PANE\" done 2>/dev/null; [ -n \"$S\" ] && tmux wait-for -S \"done-$S\" 2>/dev/null; true"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "tmux rename-window -t \"$TMUX_PANE\" NEEDS-YOU 2>/dev/null; tmux display-message -d 3000 'agent needs approval' 2>/dev/null; true"
          }
        ]
      }
    ]
  }
}
```

`$TMUX_PANE` is set in every tmux pane, so the hook targets itself. The `2>/dev/null` and trailing `true` keep it harmless outside tmux. The channel name is *derived* from the session because `wait-for` carries no payload: a single global `agent-done` channel would let the first agent to stop wake every waiter. Codex also has a `Stop` hook event (12 events in 0.157.1 and 0.162.1, checked 2026-10-12). It reads the same JSON shape from a `hooks.json` next to its config (`~/.codex/hooks.json`, or `.codex/hooks.json` in a trusted project), or the equivalent tables in `config.toml`:

```toml
# ~/.codex/config.toml
[[hooks.Stop]]
[[hooks.Stop.hooks]]
type = "command"
command = "..."   # the same Stop command as above
```

Codex runs a new hook only after you trust it; review it in `/hooks`.

**`Stop` means "turn ended", not "task done".** It fires every time the agent finishes responding, including when it stops to ask you a question. Treat `done-<session>` as "idle, go check", and let a test command decide whether the work is finished. The next section is that check.

## How do you verify a fleet's output without reading every diff?

tmux makes fan-out cheap, which makes it easy to exceed your review bandwidth. The fix is a gate that every worker passes before anyone reads its diff. Run each task through the same loop:

1. **Plan with a pass condition.** Each task slug gets one acceptance command before the agent starts, for example `npm run test:api`. A task without one does not go into the fleet.

2. **Build in its own session.** `bin/fleet` starts the agent; the `run` window stays free for the dev server.

3. **Verify on the signal, not on the agent's word.** When `done-agent-<slug>` fires, run the acceptance command in the worktree, outside the agent:

   ```bash
   slug=api-rate-limit
   if ! timeout 3600 tmux wait-for "done-agent-$slug"; then
     echo "agent-$slug: no done signal within an hour; tests not run" >&2
   elif (cd ".claude/worktrees/$slug" && npm run test:api); then
     tmux wait-for -S "ok-$slug"
   else
     tmux send-keys -t "=agent-$slug:agent" -l "npm run test:api fails in your worktree. Fix it; do not edit the tests."
     tmux send-keys -t "=agent-$slug:agent" C-m
   fi
   ```

   A timeout skips the tests rather than running them on a half-finished worktree. The `else` branch types prose, which suits an interactive agent; an exec-mode Codex worker needs a command there instead (see the Codex tab below).

4. **Review with an agent, then a human on the summary.** Run `/code-review` in the finished worktree (Claude Code) or `codex review` (Codex), and read the findings, not every line.

5. **Ship through CI.** The pull request merges only when CI is green; the human who owns the task signs off. Dependents wait on `ok-<slug>`, never on `done-agent-<slug>`.

Keep the tests out of the agent's reach, or the gate measures nothing: see [protecting the oracle](/en/workflows/test/protect-the-oracle/) and [how strong is your oracle](/en/workflows/test/oracle-strength/).

**Copy-paste prompt: turn the status line into a fleet dashboard**

```text
Write the Claude Code hook configuration that makes my tmux status line an
accurate fleet dashboard, and tell me which settings file it belongs in.

Requirements:
- Stop: rename the tmux window to "done" and signal the wait-for channel
  done-<session name>, derived from $TMUX_PANE.
- Notification: rename the window to "NEEDS-YOU" and show a
  tmux display-message for 3 seconds.
- UserPromptSubmit: restore the window name to "agent".
- Every hook exits 0 and does nothing when $TMUX_PANE is unset, because I use
  the same settings on a machine without tmux.

Then give me the ~/.tmux.conf lines that colour a window red in the status
line when its name is NEEDS-YOU. Test each hook command in a throwaway tmux
session with TMUX_PANE set by hand, show the output, and list what this setup
still cannot detect.
```

## How do you drive each agent from a tmux pane?

**Claude Code**

    `claude --worktree NAME` creates `.claude/worktrees/NAME/` on branch `worktree-NAME`; `--worktree "#1234"` branches from a pull request. On exit, Claude removes a clean worktree of an unnamed session automatically; a named session (`bin/fleet` uses `--name`) and any worktree with work in it get a keep/remove prompt. Keeping one prints the `claude --worktree <name> --resume` command to return to it. `worktree.baseRef` defaults to `"fresh"` (the remote default branch); set it to `"head"` when workers must build on your unpushed work.

    For a headless worker, `claude -p --worktree NAME "task"` skips the trust check, but it has no exit prompt, so nothing removes the worktree. Clean up with `git worktree remove` (run `git worktree unlock` first if git refuses). For a Claude-only fleet, `claude agents` (agent view, research preview) shows background sessions grouped by state; see [agent view](/en/claude-code/automate/agent-view/).

**Codex**

    `codex --worktree` starts an interactive session in a managed worktree; `codex exec --worktree "TASK"` runs one non-interactively and exits, which pairs cleanly with `wait-for`. The exit code says only that the agent stopped, so signal `done-agent-api` after it whatever the code, never `ok-api`: that is the `done-agent-$slug` channel the verification gate waits on (with `slug=api`). A run that exited non-zero then fails the gate's tests like any bad diff, instead of leaving the gate blocked for an hour on a channel nobody signals:

    ```bash
    tmux send-keys -t =agent-api:agent -l 'codex exec --worktree "add rate-limit headers to every route"; tmux wait-for -S done-agent-api'
    tmux send-keys -t =agent-api:agent C-m
    ```

    Once `codex exec` exits, the pane is back at a shell prompt, so the gate's failure branch must not type prose into it: every sentence would run as a command line. For an exec-mode worker, replace the two `send-keys` lines in the gate's `else` branch with a command that resumes the run with the fix-it message and signals again. `codex exec` prints `session id: <uuid>` in its header; pass that id, because `--last` picks the newest session for the current directory and a fleet has several:

    ```bash
    tmux send-keys -t "=agent-$slug:agent" -l "codex exec resume SESSION_ID 'npm run test:api fails in your worktree. Fix it; do not edit the tests.'; tmux wait-for -S done-agent-$slug"
    tmux send-keys -t "=agent-$slug:agent" C-m
    ```

    Codex keeps managed worktrees under `~/.codex/worktrees/<id>/<repo>/` (set `git-worktree-root` under `[desktop]` in `config.toml` to move them), not under `.claude/worktrees/`. Find the path with `git worktree list` and use it in the gate's `cd`.

    To hand a running Codex session a message without typing into its pane, use `codex queue --thread THREAD --message TEXT`. Resume a closed session with `codex resume --last`. See [Codex worktrees](/en/codex/automate/worktrees/).

**Cursor**

    Cursor's worktrees let its agent work in isolated git checkouts inside the editor (Cursor docs, checked 2026-08-28), and `.cursor/worktrees.json` customises their setup in the Agents Window, the IDE and the CLI (Cursor docs, checked 2026-10-12), so for interactive work you run agents in Cursor, not behind tmux.

    tmux earns its place with Cursor's CLI in print mode (`-p, --print`) on a remote box, driven by the same `send-keys`, `capture-pane`, and `wait-for` plumbing. The CLI command is `agent` (Cursor's CLI installation page, checked 2026-10-12), so confirm it with `agent --version` before you script it. Cursor's CLI changelog also lists `agent persist`, which keeps sessions (v2026.08.26); this page did not test whether it replaces tmux on a remote box.

## How do you keep the fleet alive when the laptop closes?

1. **Detach instead of quitting.** Press the prefix, then `d`. The agents keep running; `tmux attach -t =agent-auth-refresh` picks them back up, from another machine too.

2. **Run the server where it can stay up.** A small VPS or a spare desktop means closing the laptop stops nothing: `ssh -t box tmux attach -t =agent-auth-refresh`. For phone access to Claude Code sessions, compare [remote and mobile clients](/en/ecosystem/agent-tools/remote-mobile/).

3. **Survive reboots deliberately.** [tmux-resurrect](https://github.com/tmux-plugins/tmux-resurrect) restores the session and window layout, not the agent conversations. Install it through [TPM](https://github.com/tmux-plugins/tpm) with `set -g @plugin 'tmux-plugins/tmux-resurrect'` in `~/.tmux.conf`, then save with prefix + `Ctrl-s` and restore with prefix + `Ctrl-r`. Pair it with the agent's own resume: `claude --resume`, or `claude --worktree NAME --resume` for a kept worktree, and `codex resume`.

4. **Raise the scrollback first.** The default `history-limit` is 2000 lines; one refactor overflows it, and `capture-pane` cannot read what tmux already dropped.

## Should you use Zellij instead of tmux for agents?

[Zellij](https://github.com/zellij-org/zellij) covers the persistence and messaging half: named sessions you detach from and reattach to, and `zellij action write-chars` and `zellij action dump-screen`, which do the jobs of `send-keys` and `capture-pane`. Two gaps matter for fleets. Claude Code's `--tmux` flag and split-pane agent teams target tmux or iTerm2, not Zellij. And the Zellij CLI definition on its main branch, read 2026-09-26, has no counterpart to `wait-for`, so barriers need files or sockets instead. Pick Zellij if you already live in it and your fleet is small; pick tmux for scripted fleets.

As of 2026-09-26, tmux has 49,505 GitHub stars and Zellij 35,546 (GitHub, read 2026-09-26). tmux itself adds nothing to an agent's context window; every message you send with `send-keys` or cross-session messaging costs tokens like a typed prompt.

**Traps**

- `--tmux` without `--worktree` fails: the flag "requires --worktree".
- `--teammate-mode` exists but is experimental and does not appear in `claude --help`; set `teammateMode` in settings instead.
- Split-pane teams silently fall back to in-process under `"auto"` outside tmux and iTerm2.
- tmux-resurrect restores panes, not conversations.
- Scripts that call Cursor's CLI as `cursor-agent` rely on a name that appears on no Cursor page (checked 2026-10-12); Cursor's CLI command is `agent`.

## When tmux agent fleets break

**Two worktrees per task, or an agent deletes a directory your script expects.** You scripted worktrees the agent already manages. Remove the `git worktree` calls; the agent is the one owner.

**A message landed in the wrong session.** tmux matched a prefix: `-t agent-api` hits `agent-api-v2` when `agent-api` does not exist (reproduced on tmux 3.4). Use exact targets: `-t =agent-api` for session commands (has-session, attach, switch-client) and `-t =agent-api:agent` (or `=agent-api:`) for pane commands (send-keys, capture-pane).

**Your instruction answered a permission prompt.** `send-keys` typed into a yes/no dialog. Recover by reading the pane, rejecting or undoing what the agent did, and re-sending. Prevent it with `capture-pane` before every write, or drive handoffs off hooks.

**The message arrived mangled or killed the agent.** You forgot `-l`, and tmux read `Enter` or `C-c` in your prose as keys. Add `-l` and send `C-m` separately.

**A `capture-pane` grep misses an obvious match.** Wrapped lines split the path. Add `-J`.

**A dependent task started too early.** Either it waited on `done-agent-*` (which fires every turn) or a stale remembered signal released it. Gate on `ok-*` from the test step, and start each run with fresh channel names.

**`wait-for` hangs forever.** The worker failed before the signal line. Signal both paths (`&& tmux wait-for -S done-x || tmux wait-for -S fail-x`), and wrap waits in `timeout`.

**Split panes never appear.** You are outside tmux under `"auto"`, in an unsupported terminal (VS Code, Windows Terminal, Ghostty), or `it2` is missing. Start inside tmux, or set `"tmux"` and check `which tmux`.

**A tmux session outlives its agent team.** Run `tmux ls` and `tmux kill-session -t NAME` for the session the team created.

**Every agent stalls at once.** Every pane spends the same account's quota; an agent that "hung" has often hit a limit. Check the pane before you debug the script. For what parallel fan-out does to spend, see [cost optimization](/en/workflows/context/cost-per-context/), and for the per-developer ceiling, see [team parallelism](/en/cto-scorecard-guide/team-parallelism-tier2/).

## Where to go next with agent fleets

- [Running agents in parallel](/en/ecosystem/agent-tools/parallel-agents/) — Built-ins, desktop apps, and orchestrators compared, and when to add a third-party tool
- [herdr: an agent multiplexer](/en/ecosystem/agent-tools/herdr-agent-multiplexer/) — Agent state detection and a socket API instead of screen-scraping
- [git worktrees per agent](/en/developer-scorecard-guide/git-worktrees/) — Why filesystem isolation is load-bearing, and what it does not isolate
- [Hooks as deterministic guardrails](/en/developer-scorecard-guide/agent-hooks/) — The hook events behind the tmux signals on this page
- [Terminal mastery](/en/claude-code/build/terminal-mastery/) — The base tmux layer: prefix, panes, notifications
- [Agent tools overview](/en/ecosystem/agent-tools/) — Multiplexers, desktop environments, sandboxes, and gateways
