[BUG] Agent teams: iTerm2 split-pane mode spawns in-process teammates despite correct configuration

Found 1 possible duplicate issue:

1. https://github.com/anthropics/claude-code/issues/23572

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

Found 1 possible duplicate issue: 1. https://github.com/anthropics/claude-code/issues/23572 This issue will be automatically closed as a duplicate in 3 days. - If your issue is a duplicate, please close it and 👍 the existing issue instead - To prevent auto-closure, add a comment or 👎 this comment 🤖 Generated with Claude Code

I don't believe this is a duplicate of that issue because I have the latest version of it2 installed which includes a fix for the it2 shortcuts referenced by the other issue.

I also have this issue.

also have this issue

I tried setting from settings "teammateMode": "tmux", but didn't work. Once I used the cli flag --teammate-mode tmux, it worked. So, something about the default auto mode or reading the settings is faulty

Once I used the cli flag --teammate-mode tmux, it worked.

I just tested this and it is true.

Once I used the cli flag --teammate-mode tmux, it worked.

Worked for me as well, but only for the first time the agents are spawned in a session.
After that, I have to restart the Claude Code process to get it working again

it is also true for tmux when setting to in-process. i suspect the setting is not being honored.

setting in-process in a tmux terminal still shows the split panels

Having the same problem in WSL on ubuntu using tmux (not it2). I believe the way cli.js is written has a bug where teammateMode is only in the global settings schema, but is trying to get the value from the project schema, so no matter where you set it, it reads it as undefined, which converts it to 'auto'

I traced through the minified source and found the root cause of this — filed with details in #25772.

TL;DR: isInProcessEnabled() runs before detectAndGetBackend() and short-circuits to in-process. Its "auto" branch is just return !insideTmux() — no iTerm2 check. So if you're in iTerm2 without tmux, it always returns true and the fully-implemented ITermBackend never gets a chance to run.

The fix is a one-liner: return !insideTmux() && !isInITerm2().

Root cause identified via debug logging (v2.1.74)

Futzed around this for half a day, and Claude seems confident after a ton of debugging that this is the root cause.

Traced it through the minified source. The bug is in the isInProcessEnabled function (minified as Hx() in v2.1.74):

function Hx() {
  if (A6()) return true;  // non-interactive session → always in-process

  let mode = ZGK();  // getResolvedTeammateMode()

  if (mode === "in-process") return true;
  else if (mode === "tmux") return false;
  else return !QVT();  // !isInsideTmuxSync()
}

The else branch handles everything that isn't "in-process" or "tmux" — including "iterm2" and "auto". It returns !isInsideTmux(), which is true when you're outside tmux. So both "iterm2" and "auto" mode fall through to the else and always get treated as in-process when not inside tmux.

The full backend detection in ne() (which correctly detects iTerm2, checks for it2 CLI, etc.) is never reached because isInProcessEnabled short-circuits before it.

Additional finding: settings.json vs .claude.json

teammateMode has source: "global" in the settings schema, which means it's read from ~/.claude.json (the global state file), not ~/.claude/settings.json. Setting it in settings.json has no effect — the config is silently ignored and defaults to "auto". This is confusing since the original issue author and others (including me) naturally put it in settings.json.

Debug log evidence

With --debug-file enabled, every check shows:

[BackendRegistry] isInProcessEnabled: true (mode=iterm2, insideTmux=false)

The backend detection logs ([BackendRegistry] Starting backend detection..., iTerm2 detected, it2 CLI available: true, etc.) never appear because isInProcessEnabled gates them.

Environment

• Claude Code v2.1.74
• macOS (Darwin 25.3.0, ARM64)
• iTerm2 3.6.9
• it2 CLI working (it2 session split -v works, it2 session list works)
• Python API enabled in iTerm2 preferences
• ITERM_SESSION_ID and TERM_PROGRAM=iTerm.app both set

Suggested fix

The isInProcessEnabled function needs to return false for "iterm2" mode, and for "auto" mode it should actually run the backend detection rather than defaulting to in-process:

if (mode === "in-process") return true;
else if (mode === "tmux" || mode === "iterm2") return false;
else { /* auto: run detection */ }

This is fixed as of v2.1.77. Confirmed working — iTerm2 split panes now activate correctly without tmux.

The root cause was in isInProcessEnabled(): the "auto" branch only checked insideTmux() and had no awareness of iTerm2, so it always fell back to in-process mode before detectAndGetBackend() (which correctly detects iTerm2 + it2 CLI) was ever called.

The fix: the auto branch now checks both insideTmux() AND inITerm2() before falling back to in-process.

See #25772 for the full root cause analysis. Can this be closed?

Not OP, but I'd say yes, your analysis supports mine and I do see it working now. (I also see a followup bug, but I'll report that separately) @w4sspr

It's working for me as of now, thanks everyone

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.