devcoach

devcoach

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.

→ Why devcoach exists

---

How it works

flowchart TD

A([Task completed]) --> B{"stop-hook: 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.

→ Privacy & security

---

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](#homebrew-recommended-for-developers) — one brew install, and you get the devcoach CLI too.
• Prefer a one-click, no-terminal setup → the [Claude Code plugin](#claude-code-plugin-recommended-for-claude-code) or the [`.mcpb` extension](#claude-desktop-extension-mcpb-recommended-for-claude-desktop).
• 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](#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.

Offline install (no marketplace access)

# 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:

1. Download devcoach- .mcpb from the latest release
2. 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

npx / npm CLI (any MCP agent — no install)

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.

Manual MCP config for Claude Code (if devcoach install isn't available)

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 devcoach on your PATH, so you can drop the npx -y prefix. devcoach install detects this automatically.

Using the Claude Code plugin (above)? Skip the hooks here — the plugin already provides them.

Gemini CLI — full coaching loop (hooks + skill) — Beta

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- .zip from the latest release, unzip, then gemini extensions install . Pick one of the two (both provide the same hooks; devcoach detects the extension and skips duplicates). Details: docs/install/gemini-cli.md.

Codex CLI — full coaching loop (hooks + skill) — Beta

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