teammateMode: "tmux" does not create iTerm2 split panes despite all prerequisites met

Resolved 💬 10 comments Opened Feb 9, 2026 by sankeerthrao Closed Apr 25, 2026

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 ($TMUX is empty)

Settings

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "model": "claude-opus-4-6[1m]",
  "alwaysThinkingEnabled": true,
  "fastMode": true,
  "teammateMode": "tmux"
}

Steps to Reproduce

  1. Open iTerm2 (not inside a tmux session)
  2. Ensure it2 CLI is installed and working (it2 --version returns 0.2.3)
  3. Ensure iTerm2 Python API is enabled
  4. Set "teammateMode": "tmux" in ~/.claude/settings.json
  5. Set "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" in settings env
  6. Launch claude
  7. Ask Claude to create an agent team and spawn teammates (without run_in_background)
  8. 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 --help shows split command is available and functional
  • it2 session split --vertical works when run manually from the terminal
  • The issue persists across multiple team creation attempts

View original on GitHub ↗

This issue has 10 comments on GitHub. Read the full discussion on GitHub ↗