核心功能#

• 一个终端窗口管理所有后台运行的 Claude Code 会话
• 按状态分组：Pinned → Ready for review → Needs input → Working → Completed
• 底部输入框直接派发新任务，支持 @<repo> 指定仓库、/<skill> 指定 skill
• 选中会话按 Space Peek 快速查看，按 Enter 进入完整对话

常用快捷键#

把现有会话丢进 Agent View#

Shell 命令管理后台会话#

1
claude agents              # 打开 Agent View
2
claude attach <id>         # 进入指定会话
3
claude logs <id>           # 打印最近输出
4
claude stop <id>           # 停止会话
5
claude respawn <id>        # 重启已停止的会话
6
claude respawn --all       # 重启所有已停止会话
7
claude rm <id>             # 从列表移除（清理 worktree）
8
claude --bg "任务描述"     # 直接后台化派发新任务

文件隔离机制#

每个后台会话启动前，Claude 自动创建独立的 git worktree（.claude/worktrees/）。

worktree 的本质：git 原生功能，允许一个仓库同时拥有多个工作目录副本。它们共享同一个 .git 数据库，但文件内容是物理隔离的。Agent 在 worktree 里拥有全套项目文件，不是只复制改动的那几个。

1
原目录：tenfact_web/
2
         ├─ .git/                    ← 共享
3
         ├─ src/...                  ← 你在改的文件
4
         └─ .claude/worktrees/
5
             └─ fix-share-blank/     ← 另一个完整副本
6
                 ├─ src/...          ← Agent 在改的文件
7
                 └─ ...

清理：任务完成后 Claude Code 会把改好的内容 cherry-pick 回原分支，然后删除 worktree。残留的可以用 git worktree prune 手动清理。

全局 vs 项目级#

Agent View 显示所有项目的后台会话（全局视角），但派发新任务时默认在当前目录运行（派发视角）。按 Ctrl+S 可切换按目录分组。

现象#

在 cmux 终端中运行 claude agents，不打开 TUI 面板，而是直接打印 subagents 列表后退出：

1
19 active agents
2

3
User agents:
4
  article-summarizer · inherit
5
  refactor-agent · inherit
6
  ...

在 iTerm2 中运行则正常打开 TUI。

原因#

Agent View 是一个全屏 TUI 界面，启动前 Claude Code 会检测终端能力。cmux 底层是 Ghostty，设置了 TERM_PROGRAM=ghostty。Claude Code 的终端能力检测可能将 Ghostty 识别为不完全支持 TUI 的环境，从而 fallback 到列出 subagents。

iTerm2 的 TERM_PROGRAM=iTerm.app 被正确识别为支持 TUI 的环境。

验证#

在 cmux 中临时覆盖 TERM_PROGRAM：

1
TERM_PROGRAM=iTerm.app claude agents

如果能正常打开 TUI，就确认是 TERM_PROGRAM=ghostty 导致的检测问题。

解决方案#

方案一：在 ~/.zshrc 中给 cmux 环境设置 alias：

1
# cmux/Ghostty 兼容：让 claude agents 的 TUI 检测通过
2
if  "$TERM_PROGRAM" == "ghostty" ; then
3
  alias claude="TERM_PROGRAM=iTerm.app claude"
4
fi

方案二：在 cmux 的 Ghostty 配置中设置 term=1（不推荐，会影响其他终端能力检测）。

现象#

Claude Code 自动更新后，运行 claude agents 报错：

1
worker crashed (ENOENT: no such file or directory, posix_spawn '/opt/homebrew/Caskroom/claude-code@latest/2.1.140/claude') — respawning…

原因#

Claude Code 的 supervisor daemon 在首次启动时记录当前版本的完整二进制路径（如 2.1.140/claude）。Homebrew 升级后，新版本装进 2.1.141/，旧版本目录被移除，但旧的 daemon 进程不会自动退出。等它尝试 respawn 新进程时，找不到旧路径就报 ENOENT。

解决方案#

杀掉旧的 supervisor 进程，让它用新版本重新拉起：

1
ps aux | grep "[C]laude.*daemon" | awk '{print $2}' | xargs kill -9
2
sleep 1
3
claude agents  # supervisor 会自动用新版本启动

自动化修复#

在 ~/.zshrc 中把 ca alias 改为带自动修复的函数：

1
# Claude Code agents with auto-repair after upgrade
2
unalias ca 2>/dev/null; unfunction ca 2>/dev/null
3
ca() {
4
  command claude agents "$@"
5
  local s=$?
6
  if  $s -ne 0 ; then
7
    ps aux | grep "[C]laude.*daemon" | awk '{print $2}' | xargs kill -9 2>/dev/null
8
    sleep 1
9
    command claude agents "$@"
10
  fi
11
}

逻辑：

1. unalias + unfunction 确保 source 时不冲突
2. 第一次正常调用 claude agents
3. 如果失败（exit code ≠ 0），杀旧 daemon 再试一次
4. 正常使用时直接返回，不会多花时间

注意#

ca 原来是 alias ca='claude agents'，改为函数后用法完全一样。每次升级后不需要手动处理。

现象#

1
/Users/xiangwang/.zshrc:188: defining function based on alias `ca'
2
/Users/xiangwang/.zshrc:188: parse error near `()'

原因#

zsh 不允许在已有的 alias 基础上定义同名函数。第一次 source 时 alias ca='...' 已存在，再写 ca() { ... } 就冲突了。

解决方案#

在函数定义前加 unalias + unfunction：

1
unalias ca 2>/dev/null; unfunction ca 2>/dev/null
2
ca() { ... }

这样不管当前 shell 里 alias 还是函数已存在，都能清理干净后重新定义。

现象#

1. 用 switch-model.sh 将模型从 qwen3.6-plus 切换到 kimi-k2.6
2. 打开 Agent View 按 /model，列表里仍然只显示 qwen3.6-plus（旧模型），没有 kimi-k2.6
3. 列表中只有 Anthropic 官方模型 + 一个 custom model

原因#

Agent View 的 /model 命令列表是supervisor 启动时缓存的，不是每次打开都重新读取 settings.json。

• 官方模型（Default/Sonnet/Haiku）是内置的，始终显示
• Custom model 只显示 supervisor 启动时 settings.json 里的那个
• 后续通过 switch-model.sh 修改配置，不会通知 supervisor 刷新缓存

底部提示也说明了这一点：

“For other/previous model names, specify with —model.”

解决方案#

不需要杀 supervisor。 Agent View 的底部输入框本身就是一个命令行，支持直接输入完整模型名：

1
底部输入框:
2
> /model kimi-k2.6

按 Enter 后直接切换，绕过列表限制，即时生效。

关键记忆点#

已有后台会话的模型#

切换全局模型只影响新派发的任务。已有的后台会话锁定启动时的模型，不会自动跟随切换。需要 attach 进该会话后单独运行 /model 切换。

现象#

在 Agent View 里派发一个 agent 去改前端代码（比如调样式、修组件）。agent 在 worktree 里正常改完了，但浏览器里 localhost:5173 毫无变化，刷新也看不到效果。

原因#

Agent View 的 worktree 是一个物理上独立的目录。你的 dev server（Vite/Webpack 等）启动在原目录，监听的是原目录的文件变化，worktree 里的修改不会触发它。

1
原目录：tenfact_web/          ← dev server 在这里跑，watch 这里的文件
2
         └─ .claude/worktrees/
3
             └─ fix-share-blank/  ← Agent 在这里改，dev server 看不到

解决方案#

方案一：不用 Agent View，改用普通 /bg

如果任务需要边改边看热更新，直接用 /bg 或 claude --bg "任务" 启动普通后台会话。它在原目录运行，dev server 能实时响应。

代价：多个 /bg 同时改同一个目录会有冲突风险，只适合单人单任务。

方案二：在 worktree 里再起一个 dev server（换端口）

1
# 在 worktree 里
2
cd .claude/worktrees/fix-share-blank
3
pnpm dev --port 5174   # → localhost:5174

缺点：端口要换，agent 多了会乱。而且 agent 不会自动帮你起 server。

方案三：接受”改完再验”的节奏

Agent 在 worktree 里改完 → 你 attach 进去 review diff → 确认后合并到原分支 → 合并完你的 5173 上才能看到效果。

这是 Agent View 的标准流程，适合不需要频繁看效果的重构/逻辑修复。

适用场景建议#

核心结论：Agent View 更适合”改完再验”的任务，不适合”边改边看”的调试工作流。worktree 的隔离保护了你，也隔离了 dev server。

生成时间: 2026-05-13