devcoach 0.3.19

A local MCP server that acts as a progressive technical coach for Claude Code and Claude Desktop

devcoach

Progressive technical coaching, directly in Claude. After every task you complete with Claude Code or Claude Desktop, devcoach delivers a short, targeted lesson based on what you already know — no generic tutorials, no repeated topics.

---

How it works

flowchart TD
    A([Task completed]) --> B[Check rate limit]
    B -->|denied| Z([Silent])
    B -->|allowed| D

    subgraph loop["coaching loop"]
        D[Select topic & depth]
        E[Compose & deliver]
        G[log_lesson]
    end

    D -->|nothing| Z
    D -->|found| E
    E --> G
    G --> F([Done])
    G -.->|prompts| U(["You: ✅ ❌ ⏭"])

→ Full decision flow: session startup · lesson selection · depth calibration

Everything runs locally. No data leaves your machine. One SQLite file at ~/.devcoach/coaching.db.

---

Screenshots

Knowledge map	Lesson history	Settings

---

Installation

Step 1 — Install devcoach

Choose the method that fits your setup:

Homebrew (macOS / Linux — recommended)

brew tap UltimaPhoenix/tap && brew install devcoach

Pre-built native binary — no Python required.

uvx (no permanent install)

uvx devcoach mcp   # run the MCP server directly without installing

Requires uv · Python 3.12+

uv tool (permanent install)

uv tool install devcoach

Requires uv · Python 3.12+

---

Step 2 — Register with Claude

Run once after installing to add devcoach to your Claude config:

devcoach install

devcoach install auto-detects how it was installed and writes the correct MCP server entry. Use --mode to override if needed:

devcoach install --mode binary    # Homebrew / self-contained binary
devcoach install --mode uv-tool   # uv tool install
devcoach install --mode uvx       # uvx (no permanent install)

Restart Claude Code or Claude Desktop after running.

Manual setup (if devcoach install is not available)

Claude Code

Option A — via claude mcp CLI (recommended):

# Homebrew or uv tool (devcoach on PATH)
claude mcp add devcoach devcoach -- mcp

# uvx
claude mcp add devcoach uvx -- devcoach mcp

# global scope (all projects)
claude mcp add --scope global devcoach devcoach -- mcp

Option B — edit ~/.claude.json directly:

// Homebrew or uv tool
{ "mcpServers": { "devcoach": { "type": "stdio", "command": "devcoach", "args": ["mcp"] } } }

// uvx
{ "mcpServers": { "devcoach": { "type": "stdio", "command": "uvx", "args": ["devcoach", "mcp"] } } }

Then add the Stop hooks to ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "devcoach onboard-hook" }] },
      { "hooks": [{ "type": "command", "command": "devcoach lesson-ready" }] }
    ]
  }
}

Replace devcoach with uvx devcoach in the hook commands if using uvx.

Claude Desktop

Edit the config file for your platform:

Platform	Config file
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

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

Use "command": "uvx", "args": ["devcoach", "mcp"] if using uvx.

Claude.ai web (skill copy)

Claude.ai does not support MCP servers. Install the coaching instructions as a skill instead:

1. Copy the content of src/devcoach/SKILL.md
2. Go to claude.ai → Settings → Custom instructions (or Skills, depending on your plan)
3. 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 and is always current. If you copied it manually to Claude.ai, re-paste the latest SKILL.md after each devcoach update.

Uninstallation

1. Remove the binary

brew uninstall devcoach && brew untap UltimaPhoenix/tap   # Homebrew
uv tool uninstall devcoach                                  # uv tool
# uvx: nothing to remove

2. Remove from Claude Code

claude mcp remove devcoach   # via CLI (recommended)

Or manually remove the devcoach entry from ~/.claude.json → mcpServers, and remove the two devcoach hook entries from ~/.claude/settings.json → hooks.Stop.

3. Remove from Claude Desktop

Edit the config file for your platform (paths in the Manual setup section above) and delete the devcoach key from mcpServers.

4. Delete all devcoach data

rm -rf ~/.devcoach

This removes the coaching database, knowledge map, lessons, settings, and notebook. It cannot be undone — take a backup first if needed (devcoach backup).

---

Quick start

1. Install and register

# Pick one:
brew tap UltimaPhoenix/tap && brew install devcoach   # Homebrew
uv tool install devcoach                               # uv tool

devcoach install          # auto-detects install method, writes MCP config
# Restart Claude Code / Claude Desktop

2. Onboarding (first session)

Open Claude and start a task. devcoach will detect that setup is needed and guide you through:

• Import — restore from an existing backup zip, or
• Auto-detect — Claude scans your project files and proposes your tech stack, or
• Manual — you describe what you work with in plain conversation

Claude then proposes logical groups (Languages, Backend, DevOps, etc.) for your topics, and saves your knowledge map.

3. Work normally

You: Refactor this function to use async/await.
Claude: [does the work]

---
🎓 devcoach · Python · Level: Mid

**Structured concurrency with asyncio.TaskGroup**

TaskGroup (Python 3.12+) is the modern replacement for bare gather() calls.
Unlike gather(), it cancels sibling tasks automatically when one raises...

4. Give feedback

Use the web dashboard or CLI to record whether you understood the lesson:

devcoach feedback lesson-python-taskgroup-001 know      # understood — +1 confidence
devcoach feedback lesson-python-taskgroup-001 dont_know # need to revisit — −1 confidence

---

CLI reference

Command	Description
devcoach	Show all available commands
devcoach mcp	Start the MCP server (stdio) for Claude Code / Claude Desktop
devcoach setup	Run the onboarding wizard in the terminal
devcoach install	Register with Claude Code / 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 (favourite)
devcoach unstar <id>	Remove the starred mark from a lesson
devcoach feedback <id> <know|dont_know|clear>	Record comprehension
devcoach set max_per_day <n>	Max lessons in a 24-hour window (default 2)
devcoach set min_gap_minutes <n>	Minimum minutes between lessons (default 240)
devcoach ui	Open the web dashboard at http://localhost:7860
devcoach backup [output.zip]	Export knowledge + lessons + settings
devcoach restore <backup.zip>	Restore from a backup

Full reference: docs/cli.md

---

Web dashboard

devcoach ui

Opens at http://localhost:7860. Pages:

• Knowledge map — confidence bars for all your topics, edit mode for adjustments
• Lessons — filterable, sortable table of your full lesson history
• Settings — rate limits, import/export, backup

Full reference: docs/web-ui.md

---

MCP server (for Claude integration)

devcoach implements the MCP 2025-11-25 spec via FastMCP.

Run devcoach install to register automatically, or see Manual setup in the Installation section above for per-install-method JSON snippets.

Full MCP reference (tools, resources, data models): docs/mcp-server.md

---

Documentation

Document	Description
Getting started	Installation, onboarding, first lesson
CLI reference	All commands with examples
MCP server reference	Tools, resources, data models
Web UI	Dashboard pages and controls
Configuration	Rate limits, data location, schema, backup

---

Configuration

devcoach set max_per_day 3        # up to 3 lessons per day
devcoach set min_gap_minutes 120  # at least 2 hours between lessons

Settings are stored in ~/.devcoach/coaching.db. See docs/configuration.md for all options.

---

Publishing a new release

Tag a commit with v* to trigger the CI/CD pipeline:

git tag v1.2.3
git push origin v1.2.3

The pipeline will lint, test across Python 3.12–3.13, build, publish to PyPI via OIDC Trusted Publishing, and create a GitHub Release automatically.

First-time PyPI setup: configure a Trusted Publisher on PyPI for UltimaPhoenix/dev-coach (environment: pypi, workflow: ci.yml). No API token required after that.

---

License

Copyright 2026 UltimaPhoenix

Licensed under the Apache License, Version 2.0.

What this means for you:

• Free to use, modify, and distribute
• Commercial use and modifications must:
  • Include a copy of this license
  • State any changes made to the files
  • Retain all copyright and attribution notices
  • Include the NOTICE file in any derivative distribution
• You may not use the devcoach name or branding to endorse derived products without permission

See NOTICE for third-party attributions.