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

  1. Set teammateMode to "auto" in ~/.claude/settings.json
  2. Run Claude Code outside of tmux, directly in iTerm2
  3. Create a team and spawn a teammate
  4. Expect iTerm2 split pane to appear — but it doesn't
  5. Teammate runs in-process mode silently

Investigation

  • it2 split command works correctly and creates a new pane (it2 session split)
  • iTerm2 Python API is enabled
  • ITERM_SESSION_ID environment 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.

View original on GitHub ↗

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