它到底是什么

claude agents 是 Claude Code CLI 的顶级子命令，打开 Agent View——一个统一管理所有后台会话的终端仪表板。在同一屏幕上可以看到哪些会话正在运行、哪些在等待你的输入、哪些已完成，并可直接在底部 dispatch 新会话，无需切换标签。

该命令属于 Claude Code 后台会话管理命令组，与 claude --bg <task>（直接启动后台会话）和会话内 /bg 命令（把当前会话推入后台）共同构成完整的异步 agent 工作流。

可用性： 作为 Research Preview 上线,功能与键位可能随版本变化。Agent View 约在 v2.1.14x 系列引入(以官方 changelog 为准),建议升级到较新版本后用 claude --version 确认。各 flag 的引入版本见下方 Flag 表。

用法 / 语法

# 打开交互式 Agent View（TUI 界面）
claude agents

# 以 JSON 格式输出当前所有后台会话列表（非交互，适合脚本）
claude agents --json

# 将视图范围限定到指定工作目录
claude agents --cwd /path/to/project

# 为从 Agent View 内 dispatch 的新会话指定默认模型/effort/权限模式
claude agents --permission-mode plan --model opus --effort high

Flag 列表（均出自官方 agent-view 文档）

--permission-mode 取值与顶层 claude 命令一致(default / acceptEdits / auto / plan / bypassPermissions);其中 bypassPermissions 和 auto 需先用 claude 交互式接受过一次才能使用。--effort 取值(同顶层命令,官方 cli-reference 明确)为 low / medium / high / xhigh / max,具体可用档位取决于模型。

*上述 flag 的版本号为社区 changelog/截图推断,非官方逐条标注的精确下限,以官方 changelog 为准。

--model、--effort、--permission-mode 设置的是从 Agent View 底部 dispatch input 派发的新会话的默认值,不影响 Agent View 自身显示。

--json 输出格式

claude agents --json

以 JSON 数组输出当前活动会话的快照后退出(非 TUI 模式),加 --all 还会包含已完成的后台会话。适用于:

• tmux 状态栏集成(轮询并展示 agent 数量和状态)
• shell 脚本基于会话状态触发下游操作
• 与外部监控工具对接

官方文档列出的字段:每条都含 cwd、kind、startedAt;后台会话条目还有 id(可配合 claude attach/logs/stop)和 state(working / blocked / done / failed / stopped);进程仍存活时才有 pid 和 status,status 为 waiting 时附带 waitingFor(说明被什么阻塞,如 permission prompt / input needed);设置了名称/会话 ID 时出现 sessionId、name。可配合 --cwd <path> 过滤。

Agent View 交互界面

会话状态分组（TUI 模式下按组折叠显示）：

键盘快捷键：

界面顶部 header 显示：Claude Code 版本号、当前使用模型、工作目录、各状态会话计数。

Shell 集成 / 自动化

tmux 状态栏集成示例：

# ~/.tmux.conf 中轮询 agent 数量
set -g status-right '#(claude agents --json 2>/dev/null | jq "length" 2>/dev/null || echo "?") agents'

脚本化等待所有会话完成：

#!/bin/bash
# 轮询，直到没有处于 Working 状态的会话
while claude agents --json | jq -e '[.[] | select(.state == "working")] | length > 0' > /dev/null 2>&1; do
  echo "$(date): agents still working..."
  sleep 10
done
echo "All agents done."

后台会话的运行态字段是 state(working/blocked/done/failed/stopped);status 仅在进程存活时出现。脚本中建议加防御性解析。

与 claude --bg 配合使用：

# 并行启动多个后台任务，再用 agents 统一监控
claude --bg "为 auth 模块补充单元测试" --cwd ./packages/auth
claude --bg "生成 API 文档" --cwd ./packages/api
claude agents        # 打开 Agent View 统一查看进度

与会话内对等操作的差异

三者最终都进入同一个 Agent View 界面，区别只在于触发入口。

运行约束 / 限制

supervisor 故障恢复(daemon stop)

后台会话由一个 supervisor 进程托管。当 Agent View 报「background service did not respond」(supervisor 卡死/无响应)时,用官方 daemon 子命令恢复:

# 查看 supervisor 状态:版本、socket 目录、worker 数;未运行则退出码 1
claude daemon status

# 停掉 supervisor 及其托管的所有会话(从无响应状态恢复)
claude daemon stop --any

# 停 supervisor 但保留后台会话继续运行,下一个 supervisor 重连接管
claude daemon stop --any --keep-workers

• --keep-workers:停掉当前 supervisor 时让后台 session 继续在跑,这样下一个 supervisor 启动后会重新连接到这些幸存的 worker——避免中断长跑任务。不加此 flag 则连同托管的会话一起停掉。
• --any:确认停掉一个 on-demand supervisor(按需启动的 supervisor,即默认形态)。官方说明 --any 是默认场景下确认操作所需。

出处:官方 cli-reference 的 claude daemon stop --any 条目(示例 claude daemon stop --any --keep-workers)与 claude daemon status。用于从 unresponsive supervisor 中恢复。

经典使用场景

1. 并行多 worktree 开发

同时在多个 feature branch 上运行后台 agent，用 Agent View 统一查看哪个在等待 review 决策。

2. CI 预检脚本

# 推送前检查是否还有未完成的后台 agent
pending=$(claude agents --json --all | jq '[.[] | select(.state != "done")] | length')
if [ "$pending" -gt 0 ]; then
  echo "⚠️  还有 $pending 个 agent 未完成，确认后再推送"
  exit 1
fi

3. 批量代码库迁移监控

用 claude --bg 批量启动各子包的迁移任务，再用 claude agents 或 claude agents --json 定期检查进度，有 "Needs input" 的会话优先处理。

常见坑

--json schema 不稳定： Agent View 处于 Research Preview，--json 输出的字段结构未公开文档化，在版本升级后可能变更。脚本中建议加防御性解析（// null 默认值、try/catch 等），避免字段不存在时直接报错。

忘记把会话推入后台： claude agents 只列出后台会话。普通 claude 启动的前台会话不会自动出现，需在会话内运行 /bg 命令才能纳入 Agent View 管理。

来源

• Manage multiple agents with agent view — Claude Code Docs
• CLI reference — Claude Code Docs
• Agent view in Claude Code — Anthropic Blog
• Claude Code CLI Reference — eesel AI
• Claude Code Agent View — claudefa.st