[BUG] teammateMode: "in-process" ignored when running in iTerm2 — forced into split-pane mode

Resolved 💬 2 comments Opened Mar 24, 2026 by mjoras Closed Apr 22, 2026

Description

Setting "teammateMode": "in-process" in ~/.claude/settings.json is completely ignored when Claude Code detects it's running inside iTerm2. The BackendRegistry auto-detects inITerm2=true and forces split-pane mode regardless of the explicit user setting.

Steps to Reproduce

  1. Set "teammateMode": "in-process" in ~/.claude/settings.json:

``json
{
"teammateMode": "in-process"
}
``

  1. Run Claude Code inside iTerm2
  2. Create an agent team (TeamCreate) and spawn a teammate

Expected Behavior

Teammates should run in-process (inline in the main terminal), as configured. No split-pane prompt should appear.

Actual Behavior

  • If it2 CLI is installed: teammates spawn in iTerm2 split panes (shutdown response shows "backendType":"iterm2")
  • If it2 CLI is not installed: a prompt appears with only three options:
  1. Install it2 now — auto-installs via uvx without further confirmation
  2. Use tmux instead — opens teammates in a tmux session
  3. Cancel — skips teammate spawning entirely

There is no in-process option in this prompt. The user's explicit "in-process" setting is ignored.

Debug Log Evidence

From .claude/debug/ logs:

[BackendRegistry] Environment: insideTmux=false, inITerm2=true
[BackendRegistry] iTerm2 detected, it2 CLI available: false

The BackendRegistry detects iTerm2 and overrides the user setting. When it2 is unavailable and preferTmuxOverIterm2 is set in .claude.json, it falls back to tmux — but never to in-process.

Additional Context

  • Previously masked by "preferTmuxOverIterm2": true in ~/.claude.json, which redirected to tmux instead of iTerm2 — but still not in-process
  • Removing preferTmuxOverIterm2 caused Claude Code to prompt for iTerm2 setup and auto-install it2
  • The valid values for teammateMode are documented as "in-process", "tmux", and "auto" — but "in-process" appears to have no effect when iTerm2 is detected
  • Claude Code version: 2.1.81
  • macOS Darwin 24.6.0, iTerm2 terminal

View original on GitHub ↗

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