（1392期）claude-code-supervisor – 智能守护你的自动化编码代理

智能守护你的自动化编码代理 基于 Bash 预过滤与 LLM 智能分类的 Claude Code 会话监控方案，实现无人值守任务的错误检测、自动恢复与状态通知，提升自动化编码代理的可靠性。 使用说明 核心用法 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 成本。 原始说明 Supervise Claude Code sessions running in tmux. Uses Claude Code hooks with bash pre-filtering (Option D) and fast LLM triage to detect errors, stuck agents, and task completion. Harness-agnostic — works with OpenClaw, webhooks, ntfy, or any notification backend. Use when: (1) launching long-running Claude Code tasks that need monitoring, (2) setting up automatic nudging for API errors or premature stops, (3) getting progress reports from background coding agents, (4) continuing work after session/context limits reset. Requires: tmux, claude CLI.