Claude Forge

为 Claude Code 设计的会话治理引擎 —— 通过 Hook 机制把 Agent 路由、Skill 推荐、治理规则注入到 AI 开发流程中。

Claude Forge 是一个在本地运行的守护进程，通过 Claude Code 的 Hook API 拦截 UserPromptSubmit、PreToolUse、PostToolUse、Stop 等事件，在其中做意图分类、Agent 路由、Skill 推荐、规则阻断、治理建议。

版本: 见 cf --version · Node: >= 18 · License: MIT

核心能力

完整架构 + drawio 图见 docs/architecture/README.md

1. Hook 驱动的治理

daemon 以 Unix socket 形式与 Claude Code 的 Hook 脚本通信。每次 UserPromptSubmit / PostToolUse 等事件，daemon 在 100ms 内决定要不要往上下文注入额外指令或建议。

2. Agent 路由

基于 intent 分析（complexity、taskType）和 YAML 规则，UserPromptSubmit 阶段建议 Claude 用哪个子 agent（researcher、tester、coder 等）。路由决策全程记录到 routing_events 表，可用于离线分析和 A/B 实验。

3. Skill 推荐系统

根据用户意图和项目上下文，自动推荐合适的 Skill（如 official-debug、official-tdd、official-refactor 等）。Skill 是可复用的工作流模板，帮助 Claude 按照最佳实践完成特定类型的任务。

Agent 还可以通过 MCP 工具 skill_invoke 按需获取 Skill 的完整方法论内容（需先运行 cf mcp register）。

4. Web 管理后台

claude-forge daemon start 默认在 http://127.0.0.1:<port>（默认端口 3721，可在 ~/.claude-forge/config.yaml 的 web.port 修改）开放一个 React 管理后台，覆盖：会话浏览、事件流、执行追踪、Agent/Skill 编辑、AI 配置、实时 SSE 日志。

5. 长跑稳定性

• 自动同步：daemon 启动时自动将内置 hook 脚本同步到 ~/.claude/hooks/、将内置 skill 同步到 ~/.claude/skills/，防止 npm 升级后用户副本陈旧
• 数据 GC：每 24h 自动清理 30 天以上的 events / routing_events / skill_invocations / token_usage；每 7 天执行一次 SQLite VACUUM
• CI：GitHub Actions 在每次 push/PR 自动运行 tsc --noEmit + npm test + npm run build

安装方式说明

| 场景 | 命令 | 说明 | |---|---|---| | 普通用户 | npm i -g @winspan/claude-forge | 从 npm registry 拉最新发布版（推荐）| | 开发者本地测试 | git clone ... && cd claude-forge && npm i && npm run build && npm i -g . | 装本地代码，可能比 registry 新 | | 升级 | npm i -g @winspan/claude-forge@latest | 拉 registry 最新 |

查看实际装的版本：cf --version registry 当前最新：npm 页面

快速开始

# 1. 安装
npm install -g @winspan/claude-forge

# 2. 初始化（把 hook 脚本装到 ~/.claude/hooks/）
cf init

# 3. 配置 AI Provider（可选）
cf config

# 4. 启动 daemon
cf daemon start

# 5. 打开管理后台（默认 3721，可在 ~/.claude-forge/config.yaml 修改 web.port）
open http://127.0.0.1:3721

# 5.5（可选）注册 MCP 服务器（让 Agent 能动态调用 Skill）
cf mcp register

# 6. （可选）查看架构图
open docs/architecture/diagrams/overview.drawio  # macOS 用 drawio desktop / web 打开

之后在任何目录下开 Claude Code 会话，daemon 会自动接管 hook 事件。

CLI 命令

| 命令 | 说明 | |---|---| | cf init | 初始化 hook 脚本到 ~/.claude/hooks/ | | cf daemon {start,stop,status} | daemon 生命周期 | | cf config | AI Provider 配置（API key、base_url、model） | | cf status | 当前 daemon + Web + 存储概况 | | cf logs [--tail] | 查看 daemon 日志 | | cf stats | 近期 intent / 路由统计 | | cf rules | 查看/编辑治理规则（YAML） | | cf agents | 列出已注册 agent | | cf skills list | 列出所有 skill（内置 + 用户层） | | cf skills invoke <id> | 调用指定 skill 并打印方法论 | | cf skills sync | 同步内置 skill 到 ~/.claude/skills/ | | cf skills upgrade | AI 辅助升级 official skill（默认 dry-run，报告到 ~/.claude-forge/skill-upgrade-report.md；--apply 应用决策，自动备份 + 提示 git commit） | | cf trace <commit> | 查看 commit 关联的 session | | cf executions {list,show} | 浏览历史执行记录 | | cf mcp | MCP 配置 | | cf claudemd | 生成/更新项目 CLAUDE.md | | cf template | 模板管理 | | cf menu | 交互式菜单（推荐入口） |

也可用 claude-forge 作为 cf 的完整别名。

详细见 docs/skill-upgrade-guide.md

Web 管理后台

主要页面：

• /dashboard — 总览
• /sessions — 会话列表 + 详情
• /tasks — 任务列表 + 详情
• /events — Hook 事件流
• /skills — 在线查看 ~/.claude/skills/*.md
• /ai-config — 切换 AI Provider / 测试连接
• /reports — 周报与统计

所有列表支持搜索 + JSON/CSV 导出。

Project Map

| 模块 | 一句话职责 | |---|---| | src/core/ | 共享内核：SQLite 存储、AI provider、配置、类型契约 | | src/daemon/ | 守护进程：Unix socket server + hook 事件分发 + 服务编排 | | src/skills/ | Skill 系统：内置 18 个 + 用户层 + AI 辅助升级 | | src/web/ | Express + SSE 后端 + React 仪表盘 | | src/cli/ | claude-forge / cf 命令入口 | | src/hooks/ | bash 脚本，与 daemon 通过 Unix socket 通信 |

贡献

开发者文档见 DEVELOPMENT.md，包含仓库布局、构建/测试流程、架构说明、如何新增 Agent 或 Skill。

License

MIT © 2026 winspan