Claude Code 会话监督系统，通过 tmux 生命周期钩子 + Bash 预过滤 + LLM 分流，自动检测错误、卡死和任务完成，支持多种通知后端，适合长时间后台编码任务监控
说明：
## 核心用法
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 官方 `claude` CLI，不兼容其他 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 机制可防止无限重试，但需合理设置阈值
会员专属
