命令字典
Slash 命令、CLI 子命令、Hook 事件、启动参数的字典与演进史。
Slash 命令、CLI 子命令、Hook 事件、启动参数的字典与演进史。
以 JSON 数组打印会话/结果供脚本消费。claude agents 下列出活动后台会话（加 --all 含已完成），ultrareview 下输出原始 findings 负载。
claude agents --jsonclaude agents --json --all--json 是 claude agents 和 claude ultrareview 两个子命令各自的输出开关。两处含义不同：
| 子命令 | --json 的作用 |
|---|---|
claude agents | 把会话列表打印成 JSON 数组后立即退出，供脚本读取。默认只含活动会话，加 --all 后还包含已完成的后台会话 |
claude ultrareview [target] | 打印原始的 bugs.json payload，代替格式化后的 findings |
官方文档把 claude agents --json 称为"从 Claude Code 外部读取会话状态的受支持方式"，适用于状态栏、调度器，或监督后台工作的另一个 Claude 会话。
claude agents --json 的输出字段| 字段 | 出现条件 | 说明 |
|---|---|---|
cwd | 始终 | 工作目录 |
kind | 始终 | interactive 或 background |
startedAt | 始终 | 启动时间，Unix 毫秒 |
id | 后台会话 | 短 ID，可用于 claude attach / claude logs / claude stop |
state | 后台会话 | working / blocked / done / failed / stopped |
pid | 进程存活时 | 进程 ID |
status | 进程存活时 | busy / waiting / idle |
waitingFor | status 为 waiting 时 | permission prompt / input needed / sandbox request / worker request / dialog open |
sessionId | 有值时 | 完整会话 UUID，可用于 claude --resume |
name | 有值时 | 显示名；交互会话在被命名或接受 plan 之前显示默认名 |
# 活动会话
claude agents --json
# 含已完成的后台会话
claude agents --json --all
# 只看某目录(含子目录和 .claude/worktrees/ 下的 linked worktree)启动的会话
claude agents --json --cwd ~/projects/my-app
# ultrareview:输出原始 payload
claude ultrareview 1234 --json
配合 jq 的例子：
claude agents --json --all | jq '.[] | select(.state == "blocked")'
--json --all：官方示例组合，把已完成会话也列出来。--json --cwd <path>：按目录过滤。claude agents 还接受 --permission-mode、--model、--effort、--agent，用来设置"被派发会话"的默认值，也接受 --settings、--add-dir、--plugin-dir、--mcp-config。这些与列表输出的交互，官方文档未说明。--timeout <minutes>：等待评审完成的最长分钟数，默认 45。--post / --no-post：是否把 findings 作为一条评论发到 github.com 的 PR，默认 --no-post。两者同时传时不发帖。--json 与 --post 同用时的行为，官方文档未说明。| 约束 | 原因 |
|---|---|
--json 见于 claude agents 和 claude ultrareview | 官方 CLI 参考在这两个子命令下记录了它 |
claude agents 打开 agent view 需要交互式终端 | --json 把会话打印成 JSON 数组，供脚本读取 |
claude agents --json 默认不含已完成的后台会话，加 --all 才包含 | CLI 参考写的是 --json --all 才包含已完成的后台会话 |
claude ultrareview 需要 claude.ai 账号登录 | 它作为云端会话运行；只用 API key 需先 /login。Bedrock、Google Cloud Agent Platform、Microsoft Foundry 和启用 ZDR 的组织不可用 |
claude ultrareview 超出免费额度后按 usage credits 计费 | 必须先开启 usage credits，否则启动会被拦截 |
仓库的首个 commit 会被 claude ultrareview 子命令和 claude -p 拒绝 | 整体评审首个 commit 需要在交互式启动对话框里确认。此项要求 v2.1.277 及以上 |
claude agents --json，按 state 找出 blocked 的会话，或检查 working 的会话数量。claude ultrareview <PR号> --json 会阻塞到远端评审结束，并把原始 payload 打到 stdout。进度和会话 URL 走 stderr，所以 stdout 可以直接交给解析器。~/.claude/jobs/<id>/state.json：官方文档明确说 ~/.claude/jobs/<id>/ 下的文件不是稳定接口，会话或其他程序写入 state、detail、tempo、needs 的值会在下次更新时被覆盖。请始终用 claude agents --json。done 不等于"已结束"：一个完成了当前 turn、在等你下一条指令的会话，state 读作 done，而不是 blocked。blocked 表示会话在等你：回答它提出的问题、给出权限或 sandbox 决定、清除只有你能清除的错误（例如登录过期），或给出首个 prompt。--all 带来的会话可能没有 pid / status：这两个字段只在进程存活时出现，而 done 的会话进程可能仍存活也可能已退出，处理已完成会话时不要假设它们存在。claude ultrareview 的退出码：0 表示评审完成（无论有没有 findings），1 表示启动失败、被停止、云端会话出错或超时，130 表示被 Ctrl-C 中断。所以 exit 0 不代表没有 bug，要检查 payload。中断后远端评审仍会继续运行，可按 stderr 打印的会话 URL 查看。claude -p '/code-review ultra' 代替子命令：它只启动评审并打印跟踪链接，不等待 findings，也不会发帖。需要阻塞拿结果时用 claude ultrareview。--json 的 payload 结构：官方文档只说明它是原始 bugs.json，没有给出 schema，所以解析前请先用真实输出确认字段。