devcoach

在你的 AI 干活的同时，保持敏锐。

devcoach 可连接到 Claude Code、Claude Desktop、Gemini CLI （测试版）、Codex CLI （测试版）、Cursor、Windsurf 以及其他兼容 MCP 的工具。每当你完成一个任务，它就会根据你已有的知识水平推送一节简短、有针对性的课程——没有泛泛的教程，没有重复的主题，也无需你打开任何东西。

一切都在本地运行。没有数据会离开你的机器。只有一个 SQLite 文件，位于 ~/.devcoach/coaching.db。

基于官方的 Model Context Protocol TypeScript SDK、Node 内嵌的 node:sqlite、Hono（Web 仪表板）和 Commander（CLI）构建。需要 Node.js ≥ 24。

为什么选择 devcoach？

AI 代理如今编写了我们大量的代码——这使得我们可以在理解更少的情况下交付更多。devcoach 会把你的代理完成的每个任务变成一节简短、贴合上下文的课程，让你边做边学。更深层的赌注是：随着 AI 能力越来越强，稀缺的技能变成了验证它的产出——而这种能力只有在你持续练习时才能存活。

→ devcoach 为什么存在

Related MCP server: daruma

工作原理

flowchart TD
    A([Task completed]) --> B{"stop-hook:<br/>paced + rate limit ok?"}
    B -->|not yet| Z(["Silent — counter +1"])
    B -->|due| C["Cue: activate the devcoach skill"]

    subgraph skill["devcoach skill"]
        C --> D{"Technical work?"}
        D -->|no| S[skip_lesson]
        D -->|yes| E[Select topic & depth]
        E --> G[log_lesson]
        G --> F[Print lesson card]
    end

    S --> Y(["Silent — pacing re-armed"])
    F --> H(["Done — counter reset"])
    F -.->|prompts| U(["You: ✅ / ❌"])

→ 完整的决策流程：会话启动 · 课程选择 · 深度校准

设计保障隐私

一切都留在你的机器上。没有遥测、没有账户、没有回传。只有一个 SQLite 文件。

→ 隐私与安全

安装

devcoach 本地运行——它是一个 stdio MCP 服务器，所有数据都存储在运行代理的机器上的 ~/.devcoach/coaching.db 中。它适用于 Claude Code、Claude Desktop、Gemini CLI （测试版） 和 Codex CLI （测试版），但不适用于 claude.ai 网页版（它只支持托管/远程连接器）。

需要 Node.js ≥ 24（devcoach 使用内嵌的 node:sqlite 模块，该模块从 Node 24 起才可用）。

根据自己的工作方式来选择——每个小节都是独立的（安装并连接）：

• 开发者，习惯使用终端 → Homebrew——只需一次 brew install，你还能得到 devcoach CLI。

• 想要一键、无需终端的安装方式 → Claude Code 插件或 .mcpb 扩展。

• 使用支持注册表的 MCP 客户端？ devcoach 已列在官方 MCP Registry 中，名称为 io.gitub.UltimaPhoenix/dev-coach——可直接从那里安装。

• 其他任何方式（npx、手动配置、其他代理、claude.ai 网页版）都位于 其他安装方式 下。

Homebrew（推荐给开发者）

macOS / Linux。一次添加并信任 tap，然后安装并连接——你还能获得 devcoach CLI（因此 devcoach ui 和 CLI 无需 npx 前缀即可使用）：

# 1. Add the tap — registers github.com/UltimaPhoenix/homebrew-tap with Homebrew
brew tap UltimaPhoenix/tap

# 2. Trust the whole tap — required when Homebrew enforces HOMEBREW_REQUIRE_TAP_TRUST
brew trust --tap UltimaPhoenix/tap

# 3. Install
brew install devcoach

# 4. Connect (Homebrew puts `devcoach` on your PATH — no `npx -y` prefix needed)
devcoach install

brew tap 注册第三方仓库；brew trust --tap 将其标记为受信任，以便在设置 HOMEBREW_REQUIRE_TAP_TRUST 时 Homebrew 会加载其公式。两者都只需执行一次。之后更新：brew upgrade devcoach。一行命令：brew install UltimaPhoenix/tap/devcoach（如果你的 Homebrew 强制要求 tap 信任，请先运行 brew trust --tap UltimaPhoenix/tap）。该公式声明了 depends_on "node"，因此 Homebrew 会自动拉取最新的 Node。

Claude Code 插件（推荐给 Claude Code）——测试版

将 devcoach 添加到 Claude Code 的最简单方式——一键完成，无需任何配置。它捆绑了一切（MCP 服务器 + 自动辅导 Stop 钩子 + 技能），所以不要再运行 devcoach install（否则 Stop 钩子会被注册两次）。

# Add the marketplace once, then install (you can install any UltimaPhoenix plugin from it later)
/plugin marketplace add UltimaPhoenix/claude-plugins-marketplace
/plugin install devcoach@ultimaphoenix

MCP 服务器、钩子和技能在安装时即激活——无需重启。插件不会添加 devcoach CLI，因此请使用 npx -y devcoach ui 运行仪表板或 CLI（或使用 Homebrew / npm i -g devcoach 获得独立的 devcoach）。

# Straight from the devcoach repo (no separate marketplace)
/plugin marketplace add UltimaPhoenix/dev-coach
/plugin install devcoach@devcoach

# Offline — download devcoach-plugin-<version>.zip from a GitHub Release, unzip, then:
/plugin marketplace add /path/to/unzipped-folder
/plugin install devcoach@devcoach

有关其工作原理，请参阅 Claude Code 插件。

Claude Desktop 扩展（.mcpb）（推荐给 Claude Desktop）——测试版

一个可在 Claude Desktop 内置运行时上运行的单一捆绑包——无需 Node 或终端。每个 GitHub Release 都会附带一个：

1. 从最新发布下载 devcoach-<version>.mcpb

2. Claude Desktop → 设置 → 扩展 → 安装扩展… → 选择 .mcpb

该捆绑包是自签名的，因此 Claude Desktop 会将其作为未验证的发布者安装（要获得已验证签名，需要真实的代码签名证书）。想从源码构建？

npm run mcpb        # → dist-mcpb/devcoach-<version>.mcpb   (npm run mcpb:sign self-signs it)

其他安装方式——测试版

无需安装——npx 按需运行 devcoach。对于 Claude Code 和 Claude Desktop，一条命令即可注册 MCP 服务器、接入自动课程推送（Stop 钩子），并将辅导技能安装到 ~/.claude/skills/devcoach/：

npx -y devcoach install

之后重启你的代理。更喜欢全局二进制？运行 npm install -g devcoach，然后执行 devcoach install（并在所有地方去掉 npx -y 前缀）。升级 devcoach 后，重新运行 devcoach install 以刷新技能——devcoach stats 会在技能过期时提醒你。

选项 A——通过 claude mcp CLI（推荐）：

claude mcp add devcoach npx -- -y devcoach mcp

# all projects (user scope)
claude mcp add --scope user devcoach npx -- -y devcoach mcp

选项 B——直接编辑 ~/.claude.json：

{ "mcpServers": { "devcoach": { "type": "stdio", "command": "npx", "args": ["-y", "devcoach", "mcp"] } } }

然后，要将钩子添加到 ~/.claude/settings.json 以实现自动课程推送——stop-hook 在每轮之后判断是否该上课程， prompt-hook 在需要时提前为模型做准备：

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "npx -y devcoach stop-hook", "timeout": 60 }] }
    ],
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "npx -y devcoach prompt-hook", "timeout": 30 }] }
    ]
  }
}

提示：全局安装会将 devcoach 放到你的 PATH 中，因此你可以去掉 npx -y 前缀。devcoach install 会自动检测到这一点。 正在使用 Claude Code 插件（上文）？ 请跳过这里的钩子——插件已经提供了它们。

一条命令即可注册 MCP 服务器、AfterAgent/BeforeAgent 课程钩子和辅导技能：

npx -y devcoach install --gemini

或者安装随附的 Gemini 扩展：从最新发布下载 devcoach-gemini-extension-<version>.zip，解压，然后运行 gemini extensions install <folder>。两种方式任选其一（两者提供相同的钩子；devcoach 会检测到扩展并跳过重复项）。详情：docs/install/gemini-cli.md。

一条命令即可注册 MCP 服务器（codex mcp add）、Stop/UserPromptSubmit 课程钩子（~/.codex/hooks.json）以及辅导技能（~/.agents/skills/）：

npx -y devcoach install --codex

下次运行时，Codex 会要求你信任新的钩子——请批准它们，否则辅导将保持无效。详情：docs/install/codex.md。

将此添加到你的代理的 MCP 配置文件中（或者，如果你的客户端支持浏览 MCP Registry，可以从那里安装 io.github.UltimaPhoenix/devcoach）：

{
  "mcpServers": {
    "devcoach": {
      "command": "npx",
      "args": ["-y", "devcoach", "mcp"]
    }
  }
}

Stop 钩子（每项任务后自动推送课程）适用于 Claude Code、Gemini CLI 和 Codex CLI。此表中的代理可以完全访问所有 MCP 工具和资源——可以通过手动方式或提示你的代理来触发辅导。

Claude.ai 不支持 MCP 服务器。请改为将辅导说明作为技能安装：

1. 复制 assets/SKILL.md 的内容

2. 前往 claude.ai → 设置 → 自定义指令（或技能，具体取决于你的套餐）

3. 粘贴内容并保存

这能让 claude.ai 具备辅导行为，但没有 MCP 工具（课程记录和档案跟踪将无法工作）。

保持技能最新。 对于 Claude Code / Claude Desktop，技能会自动提供（通过 MCP 提示或插件），并且始终是最新的。如果你手动将其复制到 claude.ai，请在每次 devcoach 更新后重新粘贴最新的 SKILL.md。

上手引导

当你的代理第一次连接到 devcoach 时，它会检测到你的档案尚未设置，并引导你完成设置——无需单独的命令。（更喜欢终端？devcoach setup 会运行同样的向导。）

→ 完整的上手引导流程

阶段 1——选择如何设置你的档案

devcoach 会扫描你的完整本地 Claude Code 历史记录（代理工作过的每个项目，按最近的活跃度排序——仅文件与活动元数据，绝不包含提示文本），并提供四种方式来构建档案：

devcoach: Your knowledge profile isn't set up yet. I scanned 9 of your Claude Code
projects and found TypeScript (dev-coach), Java (discordbot), Swift (blueprince).

  1. Automatic (strongly recommended) — build the profile from that, no questions asked
  2. Automatic (Deep)   — also read my local session transcripts for a sharper profile
  3. Guided             — a step-by-step conversation about my stack
  4. Import backup      — restore a devcoach backup zip

阶段 2——构建你的档案

自动（强烈推荐）

从你的历史记录中检测到的技术栈出发，一次性构建完整的档案——主题、置信度评分、分组和辅导笔记本。无需任何提问：之后你可以（在聊天中、使用 CLI 或仪表板）查看并调整结果。

自动（深度）

自愿启用。自动模式的所有功能，外加一个独立的子代理会读取本地 Claude Code 会话记录（~/.claude/projects/）中的真实对话文本，以生成尽可能准确的档案和笔记本。首先会在滚动的 3 个月窗口上运行仅元数据的预检查；如果发现超过 8 个项目，devcoach 会询问是否缩小窗口、继续使用最近的 25 个项目，或选择特定项目。代理会事先说明：与元数据扫描相比，这会向模型分享更多你自己的本地历史——仅在这一次，在这台机器上，作为一个设置步骤。

引导式

更喜欢自己描述你的技术栈？devcoach 会询问每项技术及你的熟练程度（1–3 学习中 · 4–6 熟练 · 7–9 强 · 10 专家），与你确认主题分组，然后保存档案。

导入备份

在新机器上或重装系统后？提供备份 zip 的路径，你的完整档案——知识地图、课程、设置和笔记——将立即恢复。

阶段 3 — 档案已保存，辅导开始

保存后，你的代理会显示已设置的内容，并按照你的知识地图的组织方式分组——对于自动模式，这是你第一次看到它，所以这正是提出修改的时机：

✓ Profile saved — 24 topics across 6 groups.

### Languages
- **typescript** — 7/10
- **java** — 5/10

### DevOps
- **docker** — 7/10
- **github_actions** — 6/10

### Other
- **regex** — 4/10

Change any of this later in chat ("set my Java confidence to 7"), with the
`devcoach` CLI, or in `devcoach ui`.

就这样。你回去继续工作。辅导在后台静默进行。

你的第一课

你像往常一样处理任务。代理响应后，devcoach 会追加一课：

You: Refactor this endpoint to handle concurrent requests properly.

Agent: [refactors the code, explains the changes]

### ──────── 🎓 devcoach ────────
**Promise.allSettled vs Promise.all — don't let one failure sink the batch** · TypeScript · Mid

Promise.all rejects the moment any promise rejects, and you lose the results of
the ones that already succeeded. For independent work (fan-out fetches, batch
writes) that's usually the wrong default.

Promise.allSettled always resolves, giving you a status for every promise:

    const results = await Promise.allSettled(ids.map(fetchUser));
    const ok = results.filter(r => r.status === "fulfilled").map(r => r.value);

Use Promise.all when the tasks are genuinely all-or-nothing; reach for
allSettled when partial success is meaningful and you want to report failures.

💡 *Senior tip:* for coordinated work that *should* cancel siblings on failure,
an AbortController shared across the requests gives you all-or-nothing with
prompt cancellation — the structured-concurrency middle ground.
### ──────── typescript · mid ────────

Did that land? ✅ know (y) · ❌ don't know (n)

回复 y 或 n（或 ✅ / ❌）来调整你对该主题的熟练程度并影响未来的课程——或者直接继续：不回复即表示不改变。

截图

上下文与个性化

每节课都会存储它发生的位置——你的项目文件夹、仓库、分支、提交哈希、编辑器。你还可以通过位于 ~/.devcoach/learning-state.md 的学习笔记个性化你的辅导，它会决定 devcoach 优先处理哪些主题以及课程的深入程度。

→ 辅导笔记本 · Web 仪表盘指南

Web 仪表盘

随时打开仪表盘查看进度、编辑档案或管理设置：

npx -y devcoach ui   # → http://localhost:7860

完整参考：docs/usage/web-ui.md

CLI 参考

CLI 是用于查询和管理辅导数据的次要接口。所有功能也可以在 Web 仪表盘 中使用。运行 devcoach --help 或 devcoach <command> --help 查看完整用法。

（如果尚未全局安装，请加上 npx -y 前缀。）完整参考：docs/usage/cli.md

配置

默认设置：每天最多 2 节课，间隔至少 4 小时。 想要更多辅导？想要更少？更改即可。

devcoach set max_per_day 5           # more lessons per day
devcoach set min_gap_minutes 60      # lessons closer together

或者使用 Web 仪表盘 的设置页面。所有选项请参阅 docs/reference/configuration.md。

预期效果

在每周 1–2 个任务的典型工作周中，你会收到 2–4 节与你技术栈和熟练程度相匹配的课程。 每节课只需 30 秒阅读。经过一个月的正常 AI 辅助开发后，你将建立起一本针对自身差距的辅导笔记——你难以应对的确切模式、你容易忽略的边界情况、你不假思索就会使用的工具背后的原理。

太密集？ 调低频率：devcoach set max_per_day 1。想要更多辅导？ 调高它：devcoach set max_per_day 5。一切皆可调整。

复利效应：在工具日益强大的同时持续学习的开发者，才能始终掌控结果。

故障排查

“Node 版本错误”

devcoach 需要 Node.js ≥ 24。检查你的版本：node --version。如果低于 24，请升级：brew upgrade node（Homebrew）或 nvm install 24（如果使用 nvm）。

“MCP 服务器无法连接”

运行 devcoach install 向 Claude Code 或 Claude Desktop 重新注册服务器，然后重启代理。如果问题仍然存在，请检查 ~/.claude.json（Claude Code），确认 devcoach 条目存在且命令正确。

“辅导未触发 / 没有课程出现”

运行 devcoach doctor ——它会检查整个链路（Node 版本、~/.claude/settings.json 中的 hook 条目——以及存在时的 ~/.gemini/settings.json 和 ~/.codex/hooks.json——技能、MCP 注册、数据库、节奏计数器、速率限制），并最终给出一个结论，准确解释下一个 stop 触发点会或不会提示课程的原因。请记住，节奏控制是刻意保持安静的：在默认设置下，只有在会话中经过 nudge_every 次交互并且在速率限制内，才会提示课程——这是设计使然，不是 bug。要实时跟踪，请设置 DEVCOACH_HOOK_DEBUG=1 并查看 ~/.devcoach/hook.log：每次 hook 运行都会追加一行，记录其决定（paced (3/10)、rate limited: …、cue）。Hook 适用于 Claude Code、Gemini CLI （测试版） 和 Codex CLI （测试版）；其他代理（Cursor、Windsurf、Cline）不支持它们——可通过 MCP 工具或手动提示按需提供辅导。

课程旁出现“Stop hook error occurred”

该提示是 Claude Code 目前对任何被阻止的 Stop hook 的标注——包括 devcoach 的课程提示（旁边的“🎓 devcoach…”一行会告诉你这是辅导，而不是故障）。它无害，而且按设计也很少见：UserPromptSubmit 预载 hook 会在同一次对话轮次内提供大多数课程，因此阻塞回退只在未发生这种情况时触发。

“SQLite 权限错误”

devcoach 写入 ~/.devcoach/coaching.db。如果出现权限错误，请检查目录是否存在并且你有写权限：ls -ld ~/.devcoach。如果缺失，请运行 devcoach install 或 devcoach setup 进行初始化。

已知限制

• **claude.ai 网页版：**不支持 MCP 服务器。你可以使用 技能副本（仅辅导行为，不存储数据）。

• **临时沙箱：**如果你的代理在每次重启时运行在全新的沙箱中（如 GitHub Codespaces），devcoach 无法跨会话持久化数据。它在当前会话中可以正常工作，但课程不会延续。

• **Windows：**devcoach 已在 macOS 和 Linux 上测试。Windows 支持取决于 Node.js ≥ 24 和 node:sqlite 的可用性（通常很稳定，但如果发现问题请反馈）。

• **多用户机器：**devcoach 写入 ~/.devcoach/，因此每个用户都有自己的辅导数据库。档案不共享。

卸载

npm uninstall -g devcoach          # if installed globally (npx: nothing to remove)
brew uninstall devcoach            # if installed via Homebrew (brew untap UltimaPhoenix/tap to drop the tap)
claude mcp remove --scope user devcoach   # remove from Claude Code (install uses user scope)
rm -rf ~/.devcoach                 # delete all coaching data (back up first: devcoach backup)

对于 Claude Desktop，从平台配置文件中删除 devcoach 键（路径见上文手动设置）。同时从 ~/.claude/settings.json 中移除两个 hook 条目——一个在 hooks.Stop 下（devcoach stop-hook），一个在 hooks.UserPromptSubmit 下（devcoach prompt-hook）。

了解更多

**完整文档：**README 是快速入门。详细指南请访问 官方文档：

• devcoach 为何存在 — 核心理念

• 在你的代理中进行辅导 — 入门、你的第一课、反馈循环

• 使用 Web 仪表盘 — 个性化你的知识地图、筛选课程、跳转到代码上下文

• CLI 参考 — 用于查询和管理数据的所有命令

• 安装 — 每种安装方法，逐个代理

• 配置 — 速率限制、节奏、数据位置、架构

• 隐私与安全 — 本地优先架构、读取和存储的内容

• 工作原理 — 会话启动、辅导循环、课程选择

• 愿景与路线图 — 免费、本地、不商业化；我们正在探索的想法

• 插件市场 — UltimaPhoenix 插件集合

社区

• 给仓库加星标 — 帮助其他人发现它

• GitHub Issues — 功能请求、反馈和问题：提交 issue

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 开始。

开发

git clone https://github.com/UltimaPhoenix/dev-coach && cd dev-coach
npm install
npm run dev -- mcp        # run the MCP server from source
npm run dev -- ui         # run the web dashboard from source
npm run lint && npm run typecheck && npm test
npm run build             # tsup → dist/bin.js
npm run mcpb              # build the Claude Desktop .mcpb (npm run mcpb:sign to self-sign)

• MCP Inspector：npx @modelcontextprotocol/inspector node dist/bin.js mcp

• 技术栈：@modelcontextprotocol/sdk · node:sqlite · Hono · Commander · Zod · Biome · Vitest · tsup

发布版本

使用 v* 标记提交：

git tag v1.2.3 && git push origin v1.2.3

CI 会进行 lint、类型检查、测试（Node 24 和 26）、构建，并通过 OIDC 来源发布到 npm （npm publish --provenance）。首次设置：在 npmjs.com 上为 devcoach 包配置 Trusted Publisher（GitHub Actions，仓库 UltimaPhoenix/dev-coach，工作流 ci.yml）。

许可证

Copyright (C) 2026 UltimaPhoenix

devcoach 根据 GNU Affero General Public License v3.0（AGPL-3.0-only）授权。 你可以使用、修改和分发它——前提是你分发的任何修改版本，或作为网络服务运行 的任何修改版本，也必须在 AGPL 下以开源方式发布。目前不提供商业 许可证；如果你确实需要——将 devcoach 嵌入闭源产品或发布专有衍生品—— 提交 issue 描述你的情况，将逐案考虑。

许可常见问题

devcoach 现在和将来都 100% 免费供所有人下载、安装和使用——永远如此，包括 在工作中和商业项目上。AGPL 并不是价格标签：只有当你想在不遵守 AGPL 的情况下发布 devcoach 本身的专有/闭源衍生品时，你才需要付费。

使用 devcoach 不会让你的代码处于 AGPL 之下。 它以独立进程的方式通过 stdio/MCP 运行（npx -y devcoach mcp）；与它保持距离地交互不算衍生作品——就像查询一个 AGPL 许可的数据库一样。你自己的项目可以保留你选择的任何许可证。

• ✅ "我在构建闭源创业应用时，在 Claude Code 中使用 devcoach。" — 免费。你的应用保持专有，零义务。

• ✅ "我的整个团队安装 devcoach，以便在我们的内部/商业仓库中获得辅导。" — 免费。在公司使用未修改的工具没问题。

• ⚠️ "我 fork devcoach，添加一个功能，然后发布这个包，或者将其仪表盘作为公共服务托管。" — 你必须根据 AGPL 发布你修改后的 devcoach 源码。

• 💼 "我想把 devcoach 嵌入到我的付费产品中，并保持我的修改闭源。" — AGPL 不允许这样做；目前不提供商业许可——请先通过 issue 询问。

继续把 devcoach 当作工具/可执行文件来使用（而不是作为导入的库），AGPL 就永远不会触及你自己的代码。