智能监控后台 Claude Code 会话

Claude Code 会话监督系统，通过 tmux 生命周期钩子 + Bash 预过滤 + LLM 分流，自动检测错误、卡死和任务完成，支持多种通知后端，适合长时间后台编码任务监控

基本信息

• 技能名称?Claude Code Supervisor
• 中文名称?智能监控后台 Claude Code 会话
• 作者?johba37
• 分类?专业技能
• 版本?1.0.0
• 标签?claude-code, tmux, agent-supervision, automation, monitoring, llm-triage, background-tasks, devops, hooks

使用方法

使用说明
核心用法
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 机制可防止无限重试，但需合理设置阈值