iTerm2 native split pane not working with teammateMode auto - silently falls back to in-process
Resolved 💬 10 comments Opened Feb 9, 2026 by hulryung Closed Apr 14, 2026
Description
When using agent teams with teammateMode: "auto", iTerm2 native split panes do not appear. Claude Code silently falls back to in-process mode without any error or warning.
Environment
- OS: macOS (Darwin 25.2.0)
- Terminal: iTerm2 (
TERM_PROGRAM=iTerm.app,LC_TERMINAL=iTerm2) - it2 CLI: v0.2.0 (
pip install it2) - iTerm2 Python API: Enabled (
EnableAPIServer = 1) - tmux: v3.6a (installed, but NOT running inside tmux session)
- Claude Code settings:
``json``
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
},
"teammateMode": "auto"
}
Steps to Reproduce
- Set
teammateModeto"auto"in~/.claude/settings.json - Run Claude Code outside of tmux, directly in iTerm2
- Create a team and spawn a teammate
- Expect iTerm2 split pane to appear — but it doesn't
- Teammate runs in-process mode silently
Investigation
it2 splitcommand works correctly and creates a new pane (it2 session split)- iTerm2 Python API is enabled
ITERM_SESSION_IDenvironment variable is present- tmux split pane mode works fine when running inside a tmux session
Possible Cause
Claude Code may be looking for a different it2 command format (e.g., it2 split-pane) that doesn't exist in it2 v0.2.0. The current it2 v0.2.0 uses it2 split / it2 session split.
Expected Behavior
teammateMode: "auto"should detect iTerm2 and use native split panes via it2 CLI- If detection fails, Claude Code should log a warning instead of silently falling back to in-process mode
Workaround
Use tmux: run tmux first, then launch Claude Code. The auto mode correctly detects tmux and split panes work as expected.
This issue has 10 comments on GitHub. Read the full discussion on GitHub ↗