Command line (CLI)
What it's for: querying and managing your coaching data from the terminal — quick lookups, scripting, backups, and tuning settings without leaving the shell. It's a power-user companion to the automatic coaching in your agent; everything here is also available in the web dashboard.
The plugin does the coaching by itself and does not put devcoach on your PATH, but the CLI is a
useful companion whenever you want the dashboard or your data without going through Claude —
devcoach ui, stats, lessons, share / import, backup. Run it with npx -y devcoach …, or
install Homebrew / npm i -g devcoach for a bare command. Two commands are
not for plugin users: devcoach install and devcoach uninstall — the plugin owns the hooks and
the skill (/plugin uninstall devcoach@ultimaphoenix removes them).
Built on Commander, so every command supports --help.
devcoach --help # list all commands
devcoach <command> --help # usage for one command
devcoach --version
Prefix any command with
npx -yif you haven't installed globally (npm i -g devcoach). Mutating commands write to~/.devcoach/coaching.db; sandbox them withDEVCOACH_DIR=$(mktemp -d) devcoach ….
Setup & integration
| Command | Description |
|---|---|
devcoach mcp | Start the MCP server (stdio) — used by your agent's MCP config |
devcoach install [--claude-code] [--claude-desktop] [--gemini] [--codex] [--force] [--skip-hook] | Register the MCP server (user scope) + hooks + skill for the chosen agents; repairs stale hook layouts |
devcoach uninstall [--claude-code] [--claude-desktop] [--gemini] [--codex] [--all] [--data] [--yes] | The inverse of install: removes the MCP registration, the devcoach hook entries and the skill dirs (user hooks untouched); --data also deletes ~/.devcoach after a prompt. Run it before brew uninstall / npm uninstall -g |
devcoach doctor | Diagnose the Claude Code wiring and pacing state — explains why the next stop would or wouldn't cue a lesson |
devcoach setup | Interactive terminal onboarding wizard in four steps: backup path (or skip) → automatic or manual topics → optional groups → daily limit and minimum gap |
devcoach ui [--port <n>] [--open] | Launch the web dashboard (default port 7860; binds 127.0.0.1 only). The URL is printed as a clickable terminal link; --open also launches your default browser. Ctrl+C stops it gracefully (in-flight requests finish) |
devcoach ui --stop [--port <n>] | Stop the dashboard listening on that port — yours, or one your agent started with open_ui / /devcoach:ui (those run detached, so Ctrl+C cannot reach them) |
devcoach stop-hook / prompt-hook | Claude Code hooks (hidden from --help): Stop (onboarding check + lesson cue) and UserPromptSubmit (priming). Exit 0 always; silent or a JSON directive on stdout. Trace decisions with DEVCOACH_HOOK_DEBUG=1 |
devcoach gemini-stop-hook / gemini-prompt-hook | The same pair for Gemini CLI (beta), registered by install --gemini |
devcoach codex-stop-hook / codex-prompt-hook | The same pair for Codex (beta), registered by install --codex |
devcoach onboard-hook / lesson-ready | Legacy two-entry Stop hooks (still supported; install migrates to stop-hook) |
Knowledge map
| Command | Description |
|---|---|
devcoach profile | Show the knowledge map with confidence bars |
devcoach knowledge-add <topic> [--confidence <0-10>] [--group <name>] | Add or update a topic |
devcoach knowledge-remove <topic> | Remove a topic |
devcoach group-add <name> / group-remove <name> | Create / delete a group |
devcoach group-assign <topic> <group> | Move a topic to a group (Other to ungroup) |
Lessons
| Command | Description |
|---|---|
devcoach lessons [--period <p>] [--level <l>] [--category <c>] [--project/--repository/--branch/--commit <…>] [--starred] [--imported] [--from <name>] [--feedback <f>] [--date-from/--date-to <YYYY-MM-DD>] [--sort <col>] [--order <asc|desc>] | List lessons with filters |
devcoach lesson <id> | Show a single lesson in full |
devcoach star <id> / unstar <id> | Star / unstar |
devcoach delete <id> | Permanently delete a lesson |
devcoach feedback <id> <know|understood|dont_know|clear> | Record your answer under a lesson (know adjusts confidence) |
devcoach courses | List your step-by-step courses with progress |
devcoach course <id> | Show a course: chain, steps, progress, where its document lives |
devcoach share [id] [--last] [--link] [--file [path]] [--with-context] [--by <name> | --anonymous] | Hand a lesson to a teammate — see Sharing a lesson |
devcoach import [source] | Add a shared lesson — code, card text, link, URL, .devcoach.md, JSON export, - for stdin; no argument reads the clipboard |
Stats & settings
| Command | Description |
|---|---|
devcoach stats | Lesson counts, rate-limit status, weakest/strongest topics |
devcoach settings | Show current settings — max_per_day, min_gap_minutes, nudge_every, nudge_scope, share_name |
devcoach set max_per_day <n> | Max lessons per 24h (1–20, default 2) |
devcoach set min_gap_minutes <n> | Minimum minutes between lessons (0–1440, default 240) |
devcoach set nudge_every <n> | Interactions between lesson cues (0–1000, default 10; 0 = every turn) |
devcoach set nudge_scope <session|global> | Count interactions per chat session (default) or globally |
devcoach set share_name <name> | The sender name proposed by share (max 80 chars; empty clears → git user.name) |
Backup, export & import
Your whole profile lives in one place, so moving it between machines is a single command each way.
# Export everything → a portable zip (settings + knowledge map + lessons + notebook)
devcoach backup ~/devcoach-$(date +%F).zip # default file: devcoach-backup.zip
# Import on another machine (or restore after a reset)
devcoach restore ~/devcoach-2026-06-19.zip
| Command | Description |
|---|---|
devcoach backup [file.zip] | Export settings + knowledge map + lessons + notebook (default devcoach-backup.zip) |
devcoach restore <file.zip> | Import a backup — settings overwritten, knowledge upserted, duplicate lessons skipped |
On restore, your profile and full lesson history are merged in; you can also point the onboarding wizard at a backup. The same export/import is available in the web dashboard's Settings page. For the zip's internal format, see Configuration & data.
Sharing a lesson
One lesson, three transports — the receiver never has to tell them apart:
devcoach share --last # the card + one devcoach:lesson:1:… line → paste anywhere
devcoach share <id> --link # https://ultimaphoenix.github.io/dev-coach/lesson#devcoach:lesson:1:…
devcoach share <id> --file # writes <id>.devcoach.md (YAML front matter + markdown)
devcoach share <id> --with-context # also project/branch/commit/task — never a local folder path
devcoach share <id> --by "Ada" | --anonymous # sender name (default: share_name → git user.name)
Receiving is one command, whatever you were given:
devcoach import # no argument: reads the clipboard
devcoach import lesson.devcoach.md # a file
devcoach import "devcoach:lesson:1:…" # the code, or the whole copied card in quotes
devcoach import https://… # a share link, or any URL whose body is a shared lesson
pbpaste | devcoach import - # stdin
devcoach lessons --imported lists the lessons shared with you, --from <name> only those from one
sender (the free-text search matches sender names too). What travels, the .devcoach.md
format and how an imported lesson behaves (it never counts against max_per_day) are in the
Sharing lessons guide. --by is remembered as share_name the first time (change it
with devcoach set share_name).
Environment variables
| Variable | Effect |
|---|---|
DEVCOACH_DIR | Relocate the data directory (default ~/.devcoach) — sandboxing, tests, a second profile |
DEVCOACH_HOOK_DEBUG=1 | Trace every hook decision to ~/.devcoach/hook.log |
NO_COLOR | Disable coloured terminal output |
Examples
devcoach lessons --period week --level senior --starred
devcoach lessons --category docker --sort timestamp --order asc
devcoach feedback 9f3a know
devcoach set min_gap_minutes 120
devcoach backup ~/devcoach-$(date +%F).zip
devcoach share --last --link
devcoach import