Home

深色模式

Claude Code 分屏配置 ​

概述 ​

在 iTerm2 里开启 Claude Code Agent Teams，却仍然只看到一个终端窗口，通常不是团队没创建，而是队友仍在 in-process 模式。这个模式下，所有 teammate 都在主终端里，通过 Shift+Down 轮流切换；只有进入 split panes 模式，才会为每个 teammate 单独开 pane。

官方文档里有一个容易混淆的点：agent-teams 页面把 auto 描述成“已在 tmux 会话里才用 split panes”，settings 页面又把 auto 描述成“在 tmux 或 iTerm2 中选择分割窗格”。如果目标是在 iTerm2 里稳定分屏，最稳妥的做法不是赌 auto，而是显式开启实验开关，再把 teammateMode 设成 tmux。

两个配置文件别写反 ​

Agent Teams 相关配置分散在两个地方：

  • 实验开关 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 可以放在 shell 环境变量里，也可以写进 ~/.claude/settings.json 的 env。
  • 显示模式 teammateMode 写在 ~/.claude.json。

teammateMode 不是 settings.json 字段。Claude Code 的 settings 文档明确写到，这类全局配置项保存在 ~/.claude.json，写进 settings.json 会触发 schema 校验错误。

先启用 Agent Teams ​

Agent Teams 默认关闭。官方支持两种开启方式：

  • 在 shell 环境里导出 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。
  • 或者写进用户级 ~/.claude/settings.json。

如果希望配置能长期生效，直接写文件更省事：

json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

然后确认 Claude Code 版本不低于 v2.1.32：

sh
claude --version

如果版本太旧，先升级，再重新打开 Claude Code 会话。

让 iTerm2 具备分屏条件 ​

split-pane 模式需要二选一：

  • tmux
  • iTerm2 + it2 CLI

如果走 iTerm2 路线，官方给出的最小前置条件有三项。

先安装 it2：

sh
go install github.com/tmc/it2/cmd/it2@latest

再在 iTerm2 里打开：

text
Settings → General → Magic → Enable Python API

修改后重启 iTerm2，再验证连接：

sh
it2 auth check

这一步没过，Claude Code 通常就没法在 iTerm2 里自动创建 pane。

auto 和 tmux 该怎么选 ​

想稳定看到每个 teammate 单独占一个 pane，直接在 ~/.claude.json 里设置：

json
{
  "teammateMode": "tmux"
}

这里最容易误解的是值名。"tmux" 在 Agent Teams 文档里的含义不是“必须手动进入 tmux 会话”，而是“启用 split panes 模式”，然后 Claude Code 再根据当前终端判断用 tmux 还是 iTerm2。

常见值有三个：

  • auto：官方两页文档写法不完全一致；保守理解是“自动选择”，但在 iTerm2 里是否一定分屏，文档没有给出完全一致的描述。
  • in-process：所有 teammate 留在主终端里。
  • tmux：显式启用 split panes；在 iTerm2 下也会尝试走 iTerm2 分屏。

如果只想对单次会话禁用分屏，可以临时覆盖：

sh
claude --teammate-mode in-process

一套能直接工作的配置 ​

如果目标就是在 iTerm2 里稳定分屏，最小配置如下。

~/.claude/settings.json：

json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

~/.claude.json：

json
{
  "teammateMode": "tmux"
}

再配合两项 iTerm2 前置条件：

  • 已安装 it2 CLI。
  • 已开启 Enable Python API 并重启 iTerm2。

这一套配置的重点不是 auto，而是显式把 split-pane 模式打开。

还是单窗口时怎么排查 ​

如果已经在 iTerm2 里，但仍然没有分屏，优先检查下面几项：

  • 先按 Shift+Down。文档明确提到，队友可能已经在 in-process 模式里运行，只是当前没有显示成 pane。
  • 确认当前终端真的是 iTerm2。split-pane 模式不支持 VS Code 内置终端、Windows Terminal 和 Ghostty。
  • 检查任务是否真的适合 agent team。任务太顺序化、太小，Claude 可能根本不会生成多个 teammate。
  • 确认 it2 auth check 能通过。
  • 确认 iTerm2 的 Enable Python API 已开启，而且修改后已经重启过 iTerm2。
  • 确认 teammateMode 写在 ~/.claude.json，不是 settings.json。
  • 确认 Claude Code 版本至少是 v2.1.32。

如果更想走 tmux 路线，Agent Teams 文档仍然建议在 iTerm2 里使用 tmux -CC 作为进入 tmux 的入口点。

参考 ​