claude-code-supervisor

核心用法

Claude Code Supervisor 是一套专为长时间运行的 Claude Code 会话设计的监控基础设施。它通过拦截 Claude Code 的生命周期钩子（Stop、Error、Notification），结合 Bash 预过滤与轻量级 LLM 智能分类，实现对代理状态的实时感知与自动干预。

部署流程简洁：运行安装脚本将钩子注入目标项目，配置 YAML 文件指定分类模型与通知后端，随后在 tmux 中启动 Claude Code 任务即可。系统会自动识别会话异常（API 错误、上下文耗尽、任务完成等），并通过用户自定义的通知渠道（OpenClaw、Webhook、ntfy 等）上报，支持自动"轻推"（nudge）恢复或人工升级处理。

显著优点

分层架构降低开销：Bash 预过滤层（Option D）先处理明显场景（如正常停止、瞬态 429 错误），仅将模糊情况提交 LLM 分类，大幅减少 API 调用成本与延迟。

Harness 无关设计：不绑定特定代理框架，通过可配置的 notify.command 适配任意通知后端，从个人脚本到企业级编排系统均可集成。

双重保障机制：除钩子驱动的主动监控外，独立的 Watchdog 脚本以纯 Bash 实现（零 LLM 依赖），定期检测进程存活状态，防止 Claude Code 崩溃、OOM 或账户限流导致的监控盲区。

精细的状态分类：LLM 分类器输出五种明确状态（FINE / NEEDS_NUDGE / STUCK / DONE / ESCALATE），为下游自动化决策提供结构化输入。

潜在缺点与局限性

基础设施依赖：强制要求 tmux 与 Claude CLI，Windows 原生环境支持有限；本地 LLM 选项（如 Ollama）虽可降低云 API 依赖，但增加了部署复杂度。

配置门槛：YAML 配置、状态文件管理、tmux socket 权限等环节需要用户具备一定运维经验，非技术用户上手成本较高。

通知延迟风险：Bash 预过滤虽提升效率，但极端情况下可能误判（如将"接近完成"误判为"正常工作中"），导致通知延迟或遗漏。

权限边界模糊：通过 send-keys 向 tmux 会话注入输入的操作，若目标会话被恶意劫持，可能造成命令注入风险（尽管此风险主要源于 tmux 本身的安全配置）。

适合的目标群体

• 需要夜间/无人值守运行 Claude Code 任务的开发者与团队
• 已采用 OpenClaw、n8n、Huginn 等代理编排框架的高级用户
• 追求自动化故障恢复、减少人工监控成本的工程团队
• 具备 Bash 与 tmux 基础、愿意投入配置时间的运维人员

使用风险

配置注入风险：triage.command 与 notify.command 执行用户配置的任意命令，若配置文件被篡改，可能导致恶意代码执行。建议将配置文件纳入版本控制并设置只读权限。

tmux 会话安全：共享 tmux socket 或宽松权限设置可能允许未授权进程注入输入。应确保 socket 文件权限为 600，并限制访问用户。

LLM 服务依赖：云 API（Claude Haiku）可能因限流、故障或成本超支失效；本地模型虽可降级，但需额外维护 Ollama 等服务。

日志与隐私：尽管设计为本地优先，但通知内容可能包含项目路径、错误摘要等信息，若配置 webhook 指向第三方服务，需评估数据出境合规性。

资源占用：长时间监控大量会话时，Watchdog 的轮询机制与 LLM 分类调用可能产生不可忽视的计算与 API 成本。