Agent teams should spawn in new tmux window, not split current pane

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/23513
2. https://github.com/anthropics/claude-code/issues/23456
3. https://github.com/anthropics/claude-code/issues/23437

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

Related Feature Requests for Agent Teams

While using agent teams in production, several additional pain points surfaced:

1. TeamDelete --force for ghost agents

When agents crash (e.g., from the tmux corruption described above), they remain as "active" members in the team config. TeamDelete then refuses to clean up: "Cannot cleanup team with 2 active member(s)". Need a force flag to clean up dead agents.

2. Auto-shutdown on task completion

Agents go idle after completing work and wait indefinitely for more instructions. There should be a configurable option to auto-shutdown when:

• All assigned tasks are completed
• No new tasks are available
• An idle timeout is reached (e.g., 60s of no activity)

3. Broadcast shutdown

Currently you must send shutdown_request to each agent individually. With 4+ agents, this is tedious. A single TeamDelete or broadcast shutdown that gracefully terminates all agents would help.

4. Configurable idle timeout per agent

# Proposed
agent_config:
  idle_timeout: 60s  # auto-shutdown after 60s idle
  auto_shutdown_on_complete: true

5. Team-wide lifecycle hooks

Allow hooks on team events:

• on_agent_crash — auto-reassign tasks to leader or other agents
• on_all_tasks_complete — auto-teardown team
• on_agent_idle — configurable action (shutdown, reassign, notify)

These would make agent teams significantly more robust for daily use.

Workaround: post-spawn tmux layout rearrangement

I ran into related issues with my ultrawide setup. The main problem for me is that the lead ends up on the far left---on an ultrawide monitor that means turning your head the entire session. With many agents, the vertical-split-only approach also makes individual panes too narrow to read.

I built a tmux layout system that rearranges panes after agents spawn:

1. Let agents spawn (Claude Code does its vertical splits)
2. Wait for all agents to report in
3. Press prefix + t to rearrange into a 3-column layout

The result:

┌─────────┬──────┬──────┬─────────┐
│         │ term │ term │         │
│ agent 1 ├──────┴──────┤ agent 3 │
│         │             │         │
├─────────┤    lead     ├─────────┤
│         │  (120 cols) │         │
│ agent 2 │             │ agent 4 │
└─────────┴─────────────┴─────────┘

• Lead stays in a fixed-width center column (no more neck strain)
• Agents distribute evenly across left/right columns
• General-purpose terminal panes are preserved above the lead (for running commands, monitoring jobs, etc.)
• Dynamic auto-focus: navigating to a pane with vim keys expands it vertically in its column, so even with many agents you can always read the focused one comfortably
• prefix + y restores the original triple-column layout and kills agent panes

One thing worth noting: tmux hooks (after-split-window, pane-focus-in) conflict with Claude Code's own pane management and cause flickering, so everything has to be triggered manually via keybindings.

The config uses pane tagging (@is_center, @is_spacer) and break-pane/join-pane to rearrange without losing pane state.

This works well as a workaround, but I agree it would be much nicer to have proper customizability for how Claude Code interacts with tmux directly---configurable layout strategy, spawn target, etc.---rather than having to fix things after it's done doing its thing.

Source: https://github.com/AlexHarn/tmux-config

Also the new pane/window should not grab the input focus, because if I'm in the middle of typing something and the input focus suddenly changes then at least a few characters of my typing unavoidably go into the new pane/window, which screws up the CLI command to start the new Claude Code.

Another workaround: iTerm2 on Mac gives you a dropdown menu in the top right hand corner of each pane, this has an option to convert the pane to a window.

This reminds me of the issue you have when testing with a browser and it keeps poping up and stealing focus - perhaps a headless offscreen place should exist to launch the agents then move them to the visual panes in tmux?

Related: #26572 proposes a CustomPaneBackend protocol that eliminates this race condition by replacing split-window + send-keys with a serialized spawn_agent call. I've posted field evidence there from running 8 parallel Claude agents with structured messaging — zero send-keys, zero corruption.

The race condition you hit is reproducible at 4+ agents in the same tmux session -- the split-window approach was not designed for concurrent spawning and the send-keys timing assumptions break down fast when multiple agents start in parallel.

The new-window approach you proposed is the right fix architecturally. Each agent team gets its own tmux window rather than competing for pane splits in a shared window. A few additional patterns that have helped:

1. Stagger agent startup by 200-500ms between spawns. Crude but it avoids the concurrent send-keys collision without requiring the new-window change. Not a real fix, just a band-aid.

1. Use a named session per agent rather than pane-splitting. Something like tmux new-session -d -s agent-{name} gives each agent its own isolated session with its own shell state. You lose the visual layout of seeing all agents in one window, but you gain total isolation.

1. The new-window -n "agent-team-{team_name}" approach you proposed also makes it easy to attach/detach from individual agents selectively (tmux select-window -t agent-team-foo) instead of navigating split panes.

The quote "the future of agentic coding is bottlenecked by a tmux split-pane race condition" is accurate. This is a concrete, narrow, fixable bug (the spawning logic needs to use new-window instead of split-window) and it blocks anyone who wants to run 4+ agent teams reliably. The workaround of staggering or using separate sessions works but should not be necessary.