核心用法
Claude Code Supervisor 是一套针对 Claude Code 长期运行会话的自动化监控解决方案。它通过植入 Claude Code 生命周期钩子（Stop/Error/Notify），结合 Bash 预过滤层与轻量 LLM 分流判断，实现对后台编码 agent 的智能监督。
典型使用流程：
1. 运行 install-hooks.sh 向目标项目植入钩子脚本与配置
2. 编辑 .claude-code-supervisor.yml 配置分流模型（如 Claude Haiku 或本地 Ollama）和通知命令（OpenClaw/webhook/ntfy 等）
3. 在 tmux 会话中启动 Claude Code 任务，钩子自动捕获事件
4. Bash 预过滤处理明显情况（如 API 429 直接记录、auth 事件跳过），模糊情况交由 LLM 分流为 FINE/NEEDS_NUDGE/STUCK/DONE/ESCALATE 五类
5. 通知后端接收 cc-supervisor: 前缀消息，由 agent harness 决定是发送 "continue" 按键、更换策略，还是升维人工介入
6. 独立 watchdog 脚本周期性检测 tmux 会话与进程存活，防止 Claude Code 崩溃或 OOM 导致的监控盲区
显著优点
- 分层架构高效：Bash 处理 80% 的常规情况，LLM 仅处理需要判断的 20%，成本与延迟可控
- Harness 无关：通知层可对接 OpenClaw、webhook、ntfy 或任意脚本，不绑定特定平台
- 防御性设计：独立 watchdog 用纯 Bash 实现，即使 API 熔断、账户超限、模型宕机仍能检测死会话
- 细粒度状态追踪：通过
supervisor-state.json维护会话元数据（目标、成功标准、最大 nudge 次数、升维时限） - 会话恢复友好：支持在上下文限制重置后继续工作，适合数小时级别的长任务
潜在缺点与局限性
- 依赖 tmux：必须预先配置 tmux socket，Windows 原生环境需 WSL
- Claude CLI 独占：目前仅支持 Anthropic 官方
claudeCLI，不兼容其他 Claude API 调用方式 - 分流质量波动：Haiku 级模型对复杂终端输出模式的判断可能出现误分类（如将正常编译输出误判为 STUCK）
- 通知延迟：若选择远程 LLM 分流，网络波动会拉长 "错误发生→收到通知" 的窗口期
- 配置门槛：需要同时理解 tmux 会话管理、YAML 配置、JSON 状态文件格式，对非运维背景用户不友好
适合人群
- 需要让 Claude Code 在后台运行 30 分钟以上任务的开发者
- 已搭建 OpenClaw 或类似 agent harness 框架的高级用户
- 团队中有多个长期运行编码任务需要统一监控与自动恢复的场景
- 希望减少 "盯着终端等结果" 时间的工程师
常规风险
- 误触发 nudge：自动发送 "continue" 可能在 agent 实际等待用户输入（如 permission_prompt）时造成干扰
- 状态文件竞争：多进程同时读写
supervisor-state.json若未加锁可能导致状态不一致 - 敏感信息泄露：钩子脚本可能将终端输出片段发送至 LLM 或通知后端，需确保工作目录无硬编码密钥
- 无限循环风险：若任务本身存在逻辑 bug 导致反复失败，maxNudges 机制可防止无限重试，但需合理设置阈值