Provides progressive, in-context technical coaching by delivering personalized lessons based on the tasks completed by your AI agent.
Also known as UltimaPhoenix/dev-coach, dev-coach
- Stars
- 5
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 2.7.1
- Last commit
- Nov 15, 2026
- License
- AGPL-3.0
What is devcoach MCP?
devcoach provides progressive, in-context technical coaching by delivering personalized lessons based on the tasks completed by your AI agent.
Summary generated from the project's README
About devcoach MCP server
devcoach provides technical coaching by turning the tasks completed by your AI agent into personalized lessons. It is designed for developers who use AI agents to write code but want to maintain their own technical understanding and validation skills. The server tracks what you already know to ensure lessons are relevant and pitched at the correct difficulty level, avoiding generic tutorials or repeated topics.
This is a local MCP server that runs on your machine using Node.js 24 or higher. It stores all data in a local SQLite file at ~/.devcoach/coaching.db, ensuring no data leaves your device. It integrates with tools like Claude Code, Claude Desktop, Gemini CLI, Codex CLI, Cursor, and Windsurf. Users can manage their learning through a web dashboard or a command line interface.
Setup varies by client, offering a Homebrew installation for macOS and Linux, a dedicated Claude Code plugin, or a .mcpb extension for Claude Desktop. It uses specific stop-hooks and prompt-hooks to trigger lessons automatically after an agent finishes a task.
What you can do with it
- 1Automated technical learningAn AI agent completes a coding task and immediately provides a lesson on the specific concepts used.
- 2Personalized curriculum managementA developer can turn a difficult lesson into a structured, step-by-step course.
- 3Knowledge sharingDevelopers can export or import lessons to share technical knowledge with others.
Written from the project's README. Every use case is checked against a quote from it.
How to install devcoach MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall devcoach MCP in Claude Code
$ claude mcp add dev-coach -- npx -y devcoachInstall devcoach MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"dev-coach": {
"command": "npx",
"args": [
"-y",
"devcoach"
]
}
}
}Install devcoach MCP in VS Code
.vscode/mcp.json
{
"servers": {
"dev-coach": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"devcoach"
]
}
}
}Install devcoach MCP in VS Code CLI
$ code --add-mcp '{"name":"dev-coach","type":"stdio","command":"npx","args":["-y","devcoach"]}'Install devcoach MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"dev-coach": {
"command": "npx",
"args": [
"-y",
"devcoach"
]
}
}
}Install devcoach MCP in Codex
$ codex mcp add dev-coach -- npx -y devcoachInstall devcoach MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.dev-coach] command = "npx" args = ["-y", "devcoach"]
Install devcoach MCP in Gemini CLI
$ gemini mcp add -s user dev-coach npx -- -y devcoachInstall devcoach MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"dev-coach": {
"command": "npx",
"args": [
"-y",
"devcoach"
]
}
}
}Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableultimaphoenix/dev-coach is public and reachablegithub.com/ultimaphoenix/dev-coach ↗Pass
- Package names this repository as its sourcedevcoach names ultimaphoenix/dev-coach as sourcenpmjs.com/package/devcoach ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for devcoachnpmjs.com/package/devcoach/v/2.7.1#provenance ↗Pass
- Open source license (OSI)AGPL-3.0spdx.org/licenses/AGPL-3.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/ultimaphoenix/dev-coach ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from devcoachPass
- No critical advisory in the package or its dependencies8 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubdevcoach
Stay sharp while your AI does the work.
devcoach connects to Claude Code, Claude Desktop, Gemini CLI (beta), Codex CLI (beta), Cursor, Windsurf, and other MCP-compatible tools. When your agent finishes a task, devcoach teaches you one thing from it that you don't know yet: it keeps a map of what you already know precisely so it can skip it, and pitches each lesson at your level — no generic tutorials, no repeated topics, nothing to open.
Everything runs locally. No data leaves your machine. One SQLite file at ~/.devcoach/coaching.db.
Built on the official Model Context Protocol TypeScript SDK, Node's embedded
node:sqlite, Hono (web dashboard), and Commander (CLI). Requires Node.js ≥ 24.
Why devcoach?
AI agents now write much of our code — which makes it easy to ship more while understanding less. devcoach turns the tasks your agent finishes into short, in-context lessons on what you don't know yet, so you keep learning as you go. The deeper bet: as AI grows more capable, the scarce skill becomes validating what it produces — and that ability only survives if you keep practicing it.
How it works
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: ✅ / 💡 / ❌"])
→ Full decision flow: session startup · lesson selection · depth calibration
Privacy by design
Everything stays on your machine. No telemetry, no accounts, no calls home. Just one SQLite file.
Installation
devcoach runs locally — a stdio MCP server that stores everything in ~/.devcoach/coaching.db on the machine where your agent runs. It works in Claude Code, Claude Desktop, Gemini CLI (beta), and Codex CLI (beta), but not on claude.ai web (which only supports hosted/remote connectors).
Requires Node.js ≥ 24 (devcoach uses the embedded node:sqlite module, available only from Node 24 onward).
Pick by how you like to work — each section is self-contained (install and connect):
- Developer, comfortable in a terminal → Homebrew — one
brew install, and you get thedevcoachCLI too. - Prefer a one-click, no-terminal setup → the Claude Code plugin or the
.mcpbextension. - Registry-aware MCP client? devcoach is listed in the official MCP Registry as
io.github.UltimaPhoenix/devcoach— install it straight from there. - Anything else (npx, manual config, other agents, claude.ai web) is under Other install methods.
Homebrew (recommended for developers)
macOS / Linux. Add and trust the tap once, install, then connect — you also get the devcoach CLI (so devcoach ui and the CLI work without an npx prefix):
# 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 registers the third-party repository; brew trust --tap marks it trusted so Homebrew will load its formulae when HOMEBREW_REQUIRE_TAP_TRUST is set. Both are one-time. To update later: brew upgrade devcoach, then devcoach install again — Homebrew updates only the binary, the hooks and the skill it wired into your agents are refreshed by that second command (the Claude Code plugin does this automatically, which is why plugin + Homebrew is the nicest combination for Claude Code users: the plugin owns the coaching wiring, Homebrew adds the CLI — and then you skip devcoach install). One-liner: brew install UltimaPhoenix/tap/devcoach (run brew trust --tap UltimaPhoenix/tap first if your Homebrew enforces tap trust). The formula declares depends_on "node", so Homebrew pulls in a recent Node automatically.
Claude Code plugin (recommended for Claude Code)
The simplest way to add devcoach to Claude Code — one click, nothing to configure. It bundles everything (MCP server + automatic-coaching Stop hooks + skill), so don't also run devcoach install (or the Stop hooks get registered twice).
# 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
The MCP server, hooks, and skill activate on install — no restart needed. Open the web dashboard right from Claude Code with /devcoach:ui (or just ask — the open_ui tool); /devcoach:share and /devcoach:import hand lessons around; /devcoach:course turns a lesson you couldn't follow into a step-by-step course. Update later with /plugin marketplace update ultimaphoenix. Want what's coming next? The beta channel installs the latest canary as devcoach@ultimaphoenix-beta.
The plugin does not add the devcoach CLI, but the CLI stays a handy companion when you want the dashboard or your data without going through Claude — devcoach ui, stats, lessons, share / import, backup: run them with npx -y devcoach …, or install Homebrew / npm i -g devcoach for a bare devcoach. Just never run devcoach install next to the plugin — it owns the hooks.
# Download devcoach-plugin-<version>.zip from a GitHub Release, unzip, then:
/plugin marketplace add /path/to/unzipped-folder
/plugin install devcoach@devcoach
See Claude Code plugin for how it works.
Claude Desktop extension (.mcpb) (recommended for Claude Desktop) — Beta
A single bundle that runs on Claude Desktop's built-in runtime — no Node or terminal needed. Every GitHub Release ships one:
- Download
devcoach-<version>.mcpbfrom the latest release - Claude Desktop → Settings → Extensions → Install Extension… → pick the
.mcpb
The bundle is self-signed, so Claude Desktop installs it as an unverified publisher (a real code-signing cert would be needed for a verified signature). Prefer to build it from source?
npm run mcpb # → dist-mcpb/devcoach-<version>.mcpb (npm run mcpb:sign self-signs it)
Other install methods — Beta
No install required — npx runs devcoach on demand. For Claude Code and Claude Desktop, one command registers the MCP server, wires up automatic lesson delivery (Stop hooks), and installs the coaching skill into ~/.claude/skills/devcoach/:
npx -y devcoach install
Restart your agent afterward. Prefer a global binary? npm install -g devcoach, then run devcoach install (and drop the npx -y prefix everywhere). After upgrading devcoach, re-run devcoach install to refresh the skill — devcoach stats reminds you when it's out of date.
Canary builds: every change merged into the develop branch is published to npm under the next tag — npx -y devcoach@next (or npm install -g devcoach@next) runs the unreleased version, documented at ultimaphoenix.github.io/dev-coach/next. latest stays the last release.
Option A — via the claude mcp CLI (recommended):
claude mcp add devcoach npx -- -y devcoach mcp
# all projects (user scope)
claude mcp add --scope user devcoach npx -- -y devcoach mcp
Option B — edit ~/.claude.json directly:
{ "mcpServers": { "devcoach": { "type": "stdio", "command": "npx", "args": ["-y", "devcoach", "mcp"] } } }
Then add the hooks to ~/.claude/settings.json for automatic lesson delivery — stop-hook decides
after each turn whether a lesson is due, prompt-hook primes the model up front when one is:
{
"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 }] }
]
}
}
Tip: a global install puts
devcoachon yourPATH, so you can drop thenpx -yprefix.devcoach installdetects this automatically. Using the Claude Code plugin (above)? Skip the hooks here — the plugin already provides them.
One command registers the MCP server, the AfterAgent/BeforeAgent lesson hooks, and the coaching skill:
npx -y devcoach install --gemini
Or install the bundled Gemini extension instead: download devcoach-gemini-extension-<version>.zip from the latest release, unzip, then gemini extensions install <folder>. Pick one of the two (both provide the same hooks; devcoach detects the extension and skips duplicates). Details: docs/install/gemini-cli.md.
One command registers the MCP server (codex mcp add), the Stop/UserPromptSubmit lesson hooks (~/.codex/hooks.json), and the coaching skill (~/.agents/skills/):
npx -y devcoach install --codex
Codex asks you to trust the new hooks once on the next run — approve them or coaching stays inert. Details: docs/install/codex.md.
Add this to your agent's MCP config file (or, if your client browses the MCP Registry, install io.github.UltimaPhoenix/devcoach from there):
{
"mcpServers": {
"devcoach": {
"command": "npx",
"args": ["-y", "devcoach", "mcp"]
}
}
}
| Agent | Config file |
|---|---|
| Cursor | ~/.cursor/mcp.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
| Cline (VS Code) | VS Code Settings → cline.mcpServers |
| Continue.dev | ~/.continue/config.json → mcpServers |
| Zed | .zed/settings.json → context_servers |
Stop hooks (automatic lesson delivery after each task) exist for Claude Code, Gemini CLI, and Codex CLI. The agents in this table have full access to all MCP tools and resources — coaching can be triggered manually or by prompting your agent.
Claude.ai does not support MCP servers. Install the coaching instructions as a skill instead:
- Copy the content of
assets/SKILL.md - Go to claude.ai → Settings → Custom instructions (or Skills, depending on your plan)
- Paste the content and save
This gives claude.ai the coaching behaviour without the MCP tools (lesson logging and profile tracking will not work).
Keep the skill up to date. For Claude Code / Claude Desktop, the skill is served automatically (via the MCP prompt or the plugin) and is always current. If you copied it manually to claude.ai, re-paste the latest
SKILL.mdafter each devcoach update.
Onboarding
The first time your agent connects to devcoach it detects that your profile isn't set up and walks you through it inline — no separate command needed. (Prefer the terminal? devcoach setup runs the same wizard.)
Phase 1 — Choose how to set up your profile
devcoach scans your full local Claude Code history (every project the agent has worked in, ranked by recent activity — file and activity metadata only, never prompt text) and offers four ways to build the profile:
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
Phase 2 — Build your profile
Automatic (strongly recommended)
Builds the whole profile — topics, confidence scores, groups, and the coaching notebook — in one pass from the stack detected across your history. No questions: you review and adjust the result afterwards (in chat, with the CLI, or in the dashboard).
Automatic (Deep)
Opt-in. Everything Automatic does, plus a separate subagent reads the real conversation text of your local Claude Code session transcripts (~/.claude/projects/) for the most accurate profile and notebook it can produce. A metadata-only pre-check runs first over a rolling 3-month window; if it finds more than 8 projects, devcoach asks whether to narrow the window, proceed with the 25 most recent, or pick specific projects. The agent says so up front: this shares more of your own local history with the model than the metadata scan does — once, on this machine, as a setup step.
Guided
Prefer to describe your stack yourself? devcoach asks about each technology and your confidence level (1–3 still learning · 4–6 comfortable · 7–9 strong · 10 expert), agrees the topic groups with you, then saves the profile.
Import backup
On a new machine or reinstalling? Provide the path to your backup zip and your full profile — knowledge map, lessons, settings, and notebook — is restored instantly.
Phase 3 — Profile saved, coaching begins
After saving, your agent shows what was set up, grouped the way your knowledge map is organised — for the Automatic modes this is your first look at it, so it's the moment to ask for changes:
✓ 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`.
That's it. You go back to work. Coaching happens silently in the background.
Your first lesson
You work on a task as normal. After your agent responds, devcoach appends a lesson:
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? ✅ knew it (y) · 💡 understood (u) · ❌ couldn't follow (n)
Reply y (already knew it — confidence goes up), u (new and clear) or n (too dense — kept as a seed for a step-by-step course) to shape future lessons — or just move on: no reply means no change.
Screenshots
| Knowledge map (personalize here) | Lesson history | Settings |
|---|---|---|
![]() |
![]() |
![]() |
| A course, one step at a time |
|---|
![]() |
Context & personalization
Every lesson stores where it happened — your project folder, repository, branch, commit hash, editor. You can also personalize your coaching with a learning notebook at ~/.devcoach/learning-state.md that shapes which topics devcoach prioritises and how deep the lessons go.
→ The coaching notebook · Web dashboard guide
Web dashboard
Open the dashboard at any time to review your progress, edit your profile, or manage settings:
npx -y devcoach ui # → http://localhost:7860 (printed as a clickable link; Ctrl+C stops it)
npx -y devcoach ui --open # …and open it in your browser
npx -y devcoach ui --stop # stop a running dashboard, e.g. one your agent started
Using the Claude Code plugin? Type /devcoach:ui in Claude Code instead — no install needed (/devcoach:ui stop closes it).
| Page | What you can do |
|---|---|
| Knowledge map | See all topics with confidence bars; adjust scores directly |
| Lessons | Browse and filter your full lesson history; star lessons to revisit; share a lesson with a teammate or import theirs |
| Settings | Change rate limits, import/export your profile, take a backup |
Full reference: docs/usage/web-ui.md
Sharing lessons
A lesson that landed for you is one action away from a teammate — as copyable text (the card plus one devcoach:lesson:1:… line), a server-less link, or a .devcoach.md file. The receiver pastes, clicks or drops it into their own devcoach, where it joins the log as shared by you and never touches their daily limit. Only the lesson travels unless you include where it happened; a local path never does.
devcoach share --last # or --link / --file, --with-context, --by "Ada" / --anonymous
devcoach import # reads the clipboard; or pass a code, link, URL, file, or - for stdin
From the dashboard: ↗ Share on a lesson and + Import on the Lessons page (drop a .devcoach.md anywhere). From your agent: "share the last lesson", "import this devcoach lesson: …" — with the plugin, /devcoach:share and /devcoach:import. Full guide: docs/usage/sharing.md
CLI reference
The CLI is a secondary interface for querying and managing your coaching data. Everything is also available in the web dashboard. Run devcoach --help or devcoach <command> --help for full usage.
| Command | Description |
|---|---|
devcoach install |
Register with Claude Code (MCP + hooks + skill) / Claude Desktop |
devcoach profile |
Show your knowledge map with confidence bars |
devcoach stats |
Overview: lesson counts, weakest/strongest topics |
devcoach lessons |
Browse lesson history with filters |
devcoach lesson <id> |
Show a single lesson in full |
devcoach star <id> |
Mark a lesson as starred |
devcoach feedback <id> <know|understood|dont_know|clear> |
Record your answer under a lesson |
devcoach share [id] [--last] [--link] [--file] |
Hand a lesson to a teammate (copyable text, link or .devcoach.md) |
devcoach import [source] |
Add a shared lesson — code, link, URL or file; no argument reads the clipboard |
devcoach set max_per_day <n> |
Max lessons per day (default 2) |
devcoach set min_gap_minutes <n> |
Minutes between lessons (default 240) |
devcoach backup [file.zip] |
Export knowledge + lessons + settings + notebook |
devcoach restore <file.zip> |
Restore from a backup |
devcoach setup |
Run the onboarding wizard in the terminal |
devcoach ui |
Open the web dashboard |
(Prefix with npx -y if you haven't installed globally.) Full reference: docs/usage/cli.md
Configuration
By default: up to 2 lessons/day, at least 4 hours apart. Want more coaching? Want less? Change it.
devcoach set max_per_day 5 # more lessons per day
devcoach set min_gap_minutes 60 # lessons closer together
Or use the web dashboard Settings page. See docs/reference/configuration.md for all options.
Expected outcomes
Over a typical work week with 1–2 tasks per day, you'll receive 2–4 lessons aligned to your stack and confidence level. Each lesson takes 30 seconds to read. After a month of normal AI-assisted development, you'll have built a coaching notebook specific to your gaps — exact patterns you struggle with, edge cases you tend to miss, the reasoning behind tools you reach for instinctively.
Too intense? Dial back the frequency: devcoach set max_per_day 1. Want more coaching? Crank it up: devcoach set max_per_day 5. Everything is tunable.
The compounding effect: developers who keep learning while tools get stronger stay in control of the result.
devcoach MCP questions
How do I add devcoach MCP to Claude Code?
Run claude mcp add dev-coach -- npx -y devcoach in your terminal. Add --scope user to make it available in every project.
How do I add devcoach MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Where is the coaching data stored?
All data is stored in a single local SQLite file located at ~/.devcoach/coaching.db.



