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

[anupamchugh]

Summary

Agent teams created via Task tool with team_name spawn new tmux panes by splitting the current window. This breaks the user's existing layout and causes command corruption when multiple agents start simultaneously.

The future of agentic coding is bottlenecked by a tmux split-pane race condition.

Reproduction

1. Have a tmux session with an existing pane layout
2. Spawn 4+ agent teammates via Task tool with team_name
3. Observe: current window splits into 5+ panes
4. Observe: some agents fail to start due to tmux send-keys corruption

What Happens

• send-keys gets garbled: mmcd instead of cd, mentcd instead of cd
• Agents that receive corrupted commands fail with zsh: command not found
• User's existing tmux layout is destroyed
• 2 out of 4 agents crashed before executing any work

Expected Behavior

Agent teams should spawn in a new tmux window (or configurable target), preserving the user's current pane layout:

# Current behavior
tmux split-window -h  # splits current pane, corrupts send-keys at scale

# Proposed behavior  
tmux new-window -n "agent-team-{team_name}"
tmux split-window -h  # split within the new window

Environment

• macOS Darwin 25.1.0 (Apple Silicon)
• Claude Code with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
• tmux 3.x
• 4 agents dispatched simultaneously

Workaround

Dispatch fewer agents (2 instead of 4), or handle crashed agents' tasks in the main session.

[github-actions]

Found 3 possible duplicate issues:

1. Team agents fail to start: tmux send-keys race condition with shell initialization #23513
2. [BUG] Tmux-based team agents spawn Claude Code sessions but never receive initial prompt via mailbox #23456
3. [BUG] in-process CLI flag and config file setting are ignored, claude always launches teammembers in tmux panes from tmux #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

[anupamchugh]

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.

[AlexHarn]

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

[tpbkpkxv8x-ux]

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.

[tpbkpkxv8x-ux]

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.