teammateMode: "tmux" does not create iTerm2 split panes despite all prerequisites met
Bug Description
teammateMode: "tmux" in settings.json does not trigger iTerm2 split panes when spawning agent teammates. All agents fall back to in-process mode (confirmed via backendType: "in-process" in shutdown messages).
Environment
- Claude Code version: 2.1.32
- OS: macOS (Darwin 25.1.0)
- Terminal: iTerm2 (
TERM_PROGRAM=iTerm.app) - tmux: installed (
/opt/homebrew/bin/tmux, v3.6a) - it2 CLI: installed (
/Users/<user>/.local/bin/it2, v0.2.3) - iTerm2 Python API: Enabled (Settings → General → Magic → Enable Python API)
- Not running inside tmux (
$TMUXis empty)
Settings
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
},
"model": "claude-opus-4-6[1m]",
"alwaysThinkingEnabled": true,
"fastMode": true,
"teammateMode": "tmux"
}
Steps to Reproduce
- Open iTerm2 (not inside a tmux session)
- Ensure
it2CLI is installed and working (it2 --versionreturns0.2.3) - Ensure iTerm2 Python API is enabled
- Set
"teammateMode": "tmux"in~/.claude/settings.json - Set
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"in settings env - Launch
claude - Ask Claude to create an agent team and spawn teammates (without
run_in_background) - Teammates spawn successfully but all run in in-process mode — no iTerm2 split panes are created
Expected Behavior
Per the documentation:
The "tmux" setting enables split-pane mode and auto-detects whether to use tmux or iTerm2 based on your terminal.
Since iTerm2 is the active terminal with it2 CLI installed and Python API enabled, teammates should spawn as iTerm2 split panes.
Actual Behavior
All teammates spawn in in-process mode. The shutdown confirmation messages show "backendType": "in-process", confirming no split panes were created. The it2 CLI is functional (it2 session split works manually) but Claude Code does not invoke it.
Workaround
Running Claude Code inside a tmux session (tmux new -s claude && claude) causes teammateMode: "auto" to detect tmux and use native tmux split panes. But the "tmux" setting should handle this automatically per the docs, especially for iTerm2.
Additional Context
- Tested with 5 teammates spawned simultaneously
it2 --helpshowssplitcommand is available and functionalit2 session split --verticalworks when run manually from the terminal- The issue persists across multiple team creation attempts
This issue has 10 comments on GitHub. Read the full discussion on GitHub ↗