You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: recommend install by audience — Homebrew for devs, plugin/.mcpb for non-experts
- recommendation reframed by who you are, not just your agent:
Homebrew (CLI/developers) · Claude Code plugin & Claude Desktop .mcpb (one-click, non-expert)
- README: Homebrew promoted to a first-class section (first), one-click options next,
and npx / manual config / other agents / claude.ai moved into collapsible <details>
- docs: 'Which method is right for you?' + a Best-for table in install/index;
Recommended admonitions on the homebrew / plugin / claude-desktop pages
- sidebar: Installation reordered to mirror the preferred order (Homebrew first)
Docusaurus build clean (no broken links).
Copy file name to clipboardExpand all lines: README.md
+51-47Lines changed: 51 additions & 47 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -53,27 +53,43 @@ flowchart TD
53
53
54
54
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** and **Claude Desktop**, but **not** on claude.ai web (which only supports hosted/remote connectors). Requires **Node.js ≥ 24**.
55
55
56
-
Pick the method that matches your setup — each section below is self-contained (install **and** connect):
56
+
**Pick by how you like to work** — each section is self-contained (install **and** connect):
57
57
58
-
| Your setup | Method |
59
-
|------------|--------|
60
-
|**Claude Code**|**1. Plugin** — bundles the MCP server, hooks & skill in one install *(recommended)*|
-**Developer, comfortable in a terminal → [Homebrew](#homebrew-recommended-for-developers)** — one `brew install`, and you get the `devcoach` CLI too.
59
+
-**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)**.
60
+
- Anything else (npx, manual config, other agents, claude.ai web) is under **[Other install methods](#other-install-methods)**.
65
61
66
-
### 1. Claude Code plugin (recommended)
62
+
### Homebrew (recommended for developers)
67
63
68
-
The plugin bundles **everything** — the MCP server, the automatic-coaching Stop hooks, and the coaching skill — so there's nothing else to wire up and **no need to run `devcoach install`** (don't do both, or the Stop hooks get registered twice).
64
+
macOS / Linux. Add and trust the tap once, install, then connect — you also get the **`devcoach` CLI** (so [`devcoach ui`](#web-dashboard) and the [CLI](docs/usage/cli.md) work without an `npx` prefix):
65
+
66
+
```bash
67
+
# 1. Add the tap — registers github.com/UltimaPhoenix/homebrew-tap with Homebrew
68
+
brew tap UltimaPhoenix/tap
69
+
70
+
# 2. Trust the whole tap — required when Homebrew enforces HOMEBREW_REQUIRE_TAP_TRUST
71
+
brew trust --tap UltimaPhoenix/tap
72
+
73
+
# 3. Install
74
+
brew install devcoach
75
+
76
+
# 4. Connect (Homebrew puts `devcoach` on your PATH — no `npx -y` prefix needed)
77
+
devcoach install
78
+
```
79
+
80
+
`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`. 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.
81
+
82
+
### Claude Code plugin (recommended for Claude Code)
83
+
84
+
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).
69
85
70
86
```bash
71
87
# Add the marketplace once, then install (you can install any UltimaPhoenix plugin from it later)
The MCP server, hooks, and skill activate on install — no restart needed.
92
+
The MCP server, hooks, and skill activate on install — no restart needed. The plugin **does not** add the `devcoach` CLI, so run the dashboard or CLI with `npx -y devcoach ui` (or use Homebrew / `npm i -g devcoach` for a bare `devcoach`).
77
93
78
94
<details>
79
95
<summary><strong>Other ways to install the plugin</strong> (straight from the repo · offline zip)</summary>
@@ -90,9 +106,23 @@ The MCP server, hooks, and skill activate on install — no restart needed.
90
106
91
107
</details>
92
108
93
-
The plugin runs the published `devcoach` npm package via `npx`, so it needs **Node.js ≥ 24** and runs **locally only**. See [Claude Code plugin](docs/install/claude-code-plugin.md) for how it works.
109
+
See [Claude Code plugin](docs/install/claude-code-plugin.md) for how it works.
110
+
111
+
### Claude Desktop extension (`.mcpb`) (recommended for Claude Desktop)
112
+
113
+
A single bundle that runs on Claude Desktop's built-in runtime — no Node or terminal needed:
114
+
115
+
```bash
116
+
npm run mcpb # → dist-mcpb/devcoach-<version>.mcpb
117
+
# Claude Desktop → Settings → Extensions → Install Extension… → pick the .mcpb
118
+
```
119
+
120
+
`npm run mcpb:sign` self-signs it (installs as an *unverified publisher*; a real code-signing cert is needed for a verified signature). Prebuilt `.mcpb` releases and a Desktop directory listing are planned.
121
+
122
+
### Other install methods
94
123
95
-
### 2. npx CLI (any MCP agent)
124
+
<details>
125
+
<summary><strong>npx / npm CLI</strong> (any MCP agent — no install)</summary>
96
126
97
127
No install required — `npx` runs devcoach on demand. For **Claude Code** and **Claude Desktop**, one command registers the MCP server and wires up automatic lesson delivery:
98
128
@@ -102,6 +132,8 @@ npx -y devcoach install
102
132
103
133
Restart your agent afterward. Prefer a global binary? `npm install -g devcoach`, then run `devcoach install` (and drop the `npx -y` prefix everywhere).
104
134
135
+
</details>
136
+
105
137
<details>
106
138
<summary><strong>Manual MCP config for Claude Code</strong> (if <code>devcoach install</code> isn't available)</summary>
107
139
@@ -134,12 +166,12 @@ Then add the Stop hooks to `~/.claude/settings.json` for automatic lesson delive
134
166
```
135
167
136
168
> Tip: a global install puts `devcoach` on your `PATH`, so you can drop the `npx -y` prefix. `devcoach install` detects this automatically.
137
-
> **Using the [Claude Code plugin](#1-claude-code-plugin-recommended)?** Skip the hooks above — the plugin already provides them.
169
+
> **Using the Claude Code plugin (above)?** Skip the hooks here — the plugin already provides them.
@@ -166,38 +198,8 @@ Add this to your agent's MCP config file:
166
198
167
199
</details>
168
200
169
-
### 3. Homebrew (macOS / Linux)
170
-
171
-
devcoach ships from its own tap. Add and trust the repository once, install, then connect:
172
-
173
-
```bash
174
-
# 1. Add the tap — registers github.com/UltimaPhoenix/homebrew-tap with Homebrew
175
-
brew tap UltimaPhoenix/tap
176
-
177
-
# 2. Trust the whole tap — required when Homebrew enforces HOMEBREW_REQUIRE_TAP_TRUST
178
-
brew trust --tap UltimaPhoenix/tap
179
-
180
-
# 3. Install
181
-
brew install devcoach
182
-
183
-
# 4. Connect (Homebrew puts `devcoach` on your PATH — no `npx -y` prefix needed)
184
-
devcoach install
185
-
```
186
-
187
-
`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`. 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.
188
-
189
-
### 4. Claude Desktop extension (`.mcpb`)
190
-
191
-
A single bundle that runs on Claude Desktop's built-in runtime — no Node or terminal needed:
192
-
193
-
```bash
194
-
npm run mcpb # → dist-mcpb/devcoach-<version>.mcpb
195
-
# Claude Desktop → Settings → Extensions → Install Extension… → pick the .mcpb
196
-
```
197
-
198
-
`npm run mcpb:sign` self-signs it (installs as an *unverified publisher*; a real code-signing cert is needed for a verified signature). Prebuilt `.mcpb` releases and a Desktop directory listing are planned.
199
-
200
-
### 5. claude.ai web (skill copy)
201
+
<details>
202
+
<summary><strong>claude.ai web</strong> (skill copy — no MCP)</summary>
201
203
202
204
Claude.ai does not support MCP servers. Install the coaching instructions as a skill instead:
203
205
@@ -209,6 +211,8 @@ This gives claude.ai the coaching behaviour without the MCP tools (lesson loggin
209
211
210
212
> **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.md` after each devcoach update.
0 commit comments