feat(plugin): drop npx — install pinned devcoach from npm once, run via node

The plugin previously fetched devcoach via `npx -y` on every MCP launch AND every
Stop hook (which fire after each turn). Now it ships only config + a tiny bootstrap
(plugin/scripts/launch.mjs) — no committed binary:

- launch.mjs installs the pinned version (plugin/package.json) once into the plugin's
  persistent data dir (${CLAUDE_PLUGIN_DATA}), then runs dist/bin.js in-process; it
  re-installs only when a plugin update bumps the pin
- .mcp.json + both Stop hooks call `node ${CLAUDE_PLUGIN_ROOT}/scripts/launch.mjs <cmd>`
  — zero per-invocation npx (warm hook run measured ~0.15s vs npx resolution each time)
- npm stays the single source of truth (no build artifact in git); sync-plugin.mjs keeps
  the pin in lockstep with package.json and CI commits plugin/package.json on release

Verified: launcher installs devcoach@0.3.65 from npm, --version dispatches, and the MCP
server answers initialize through the launcher. Docs updated; Docusaurus build clean.

Author: UltimaPhoenix

.github/workflows/ci.yml

@@ -130,7 +130,7 @@ jobs:
           git config user.name  "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git add package.json package-lock.json mcpb/manifest.json \
-            plugin/.claude-plugin/plugin.json plugin/skills/devcoach/SKILL.md
+            plugin/.claude-plugin/plugin.json plugin/skills/devcoach/SKILL.md plugin/package.json
           git commit -m "chore: release v${NEW}"
           git tag "v${NEW}"
           git push origin HEAD:main "v${NEW}"

.gitignore

@@ -8,6 +8,9 @@ dist-plugin/
 mcpb/build/
 *.tsbuildinfo
 
+# Plugin launcher's runtime fallback data dir (real one is ${CLAUDE_PLUGIN_DATA})
+plugin/.data/
+
 # MCPB signing keys (generated by `npm run mcpb:sign --self-signed`)
 mcpb/cert.pem
 mcpb/key.pem

docs/install/claude-code-plugin.md

@@ -45,21 +45,25 @@ unzip it, then point Claude Code at the unzipped folder:
 
 ## How it works
 
-When you enable the plugin, Claude Code wires in its three component files:
-
-1. **`.mcp.json`** → Claude Code launches the MCP server locally as a stdio process
-   (`npx -y devcoach mcp`). It opens `~/.devcoach/coaching.db` (SQLite), derived from your home
-   directory.
-2. **`hooks/hooks.json`** → after every turn, Claude Code runs the two `Stop` hooks (also local
-   `npx -y devcoach` processes). They read the same database and either stay silent or nudge the agent
-   to run onboarding / deliver a lesson. This is what makes coaching automatic.
+When you enable the plugin, Claude Code wires in its component files. The plugin ships only config plus a
+small bootstrap (`scripts/launch.mjs`) — **no bundled binary and no per-call `npx`**. On first use the
+launcher installs the *pinned* `devcoach` version (from `plugin/package.json`) **once** into the plugin's
+persistent data dir, then runs it directly with `node`; later calls (every hook fire, every server start)
+skip straight to `node` — and it only re-installs when a plugin update bumps the pinned version.
+
+1. **`.mcp.json`** → Claude Code launches the MCP server as a local stdio process
+   (`node ${CLAUDE_PLUGIN_ROOT}/scripts/launch.mjs mcp`). It opens `~/.devcoach/coaching.db` (SQLite),
+   derived from your home directory.
+2. **`hooks/hooks.json`** → after every turn, Claude Code runs the two `Stop` hooks through the same
+   launcher. They read the same database and either stay silent or nudge the agent to run onboarding /
+   deliver a lesson. This is what makes coaching automatic — and with no `npx` per fire, it's snappy.
 3. **`skills/devcoach/SKILL.md`** → the coaching playbook, auto-loaded so the agent knows *how* to
    teach when a hook fires.
 
 ## Running the CLI & web dashboard
 
-The plugin gives Claude Code everything it needs to coach you, but it does **not** put the `devcoach`
-**CLI** on your `PATH` — it runs the MCP server internally via `npx`. So to open the
+The plugin gives Claude Code everything it needs to coach you, but it keeps devcoach inside its own data
+dir — it does **not** put the `devcoach` **CLI** on your `PATH`. So to open the
 [web dashboard](../usage/web-ui.md) or use any [CLI command](../usage/cli.md), prefix it with `npx -y`:
 
 ```bash
@@ -84,7 +88,7 @@ machine's home directory:
   persisted across runs. Use [`devcoach backup`](../usage/cli.md#backup-export--import) / `restore` to
   carry your profile between machines.
 
-It needs **Node.js ≥ 24** (for Node's embedded `node:sqlite`), since the plugin runs the published
-`devcoach` npm package via `npx`.
+It needs **Node.js ≥ 24** (for Node's embedded `node:sqlite`) and a one-time network connection on first
+use (to install the pinned `devcoach` package into the plugin's data dir); after that it runs offline.
 
 → Next: **[Coaching in your agent](../usage/coaching.md)**.

plugin/.mcp.json

@@ -2,8 +2,8 @@
   "mcpServers": {
     "devcoach": {
       "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "devcoach", "mcp"]
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/launch.mjs", "mcp"]
     }
   }
 }

plugin/hooks/hooks.json

@@ -1,8 +1,8 @@
 {
   "hooks": {
     "Stop": [
-      { "hooks": [{ "type": "command", "command": "npx -y devcoach onboard-hook" }] },
-      { "hooks": [{ "type": "command", "command": "npx -y devcoach lesson-ready" }] }
+      { "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/launch.mjs\" onboard-hook" }] },
+      { "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/launch.mjs\" lesson-ready" }] }
     ]
   }
 }

plugin/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "devcoach-plugin",
+  "private": true,
+  "description": "Pins the published devcoach version the plugin installs once into its data dir (see scripts/launch.mjs).",
+  "dependencies": {
+    "devcoach": "0.3.65"
+  }
+}

plugin/scripts/launch.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// devcoach Claude Code plugin bootstrap.
+//
+// The plugin ships only config + this launcher — the actual devcoach binary comes from npm, so there's
+// no committed build artifact and no per-invocation `npx`. On first use we install the *pinned* version
+// (plugin/package.json) once into the plugin's persistent data dir (${CLAUDE_PLUGIN_DATA}), then run it
+// in-process. Subsequent calls (the MCP server start + every Stop hook) just run `node` against the
+// installed binary; we only re-install when the pinned version changes.
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const root = process.env.CLAUDE_PLUGIN_ROOT ?? join(import.meta.dirname, "..");
+const data = process.env.CLAUDE_PLUGIN_DATA ?? join(root, ".data");
+const srcManifest = join(root, "package.json");
+const dstManifest = join(data, "package.json");
+const binJs = join(data, "node_modules", "devcoach", "dist", "bin.js");
+
+mkdirSync(data, { recursive: true });
+const want = readFileSync(srcManifest, "utf8");
+const have = existsSync(dstManifest) ? readFileSync(dstManifest, "utf8") : "";
+if (!existsSync(binJs) || have !== want) {
+  copyFileSync(srcManifest, dstManifest);
+  // stdio "ignore": npm output must not touch the MCP server's stdout (protocol) or a hook's stderr (cue).
+  const r = spawnSync("npm", ["install", "--omit=dev", "--no-audit", "--no-fund", "--no-progress"], {
+    cwd: data,
+    stdio: "ignore",
+  });
+  if (r.status !== 0 || !existsSync(binJs)) {
+    console.error("devcoach plugin: could not install the devcoach package (needs Node ≥24 + network on first run).");
+    process.exit(0); // stay silent rather than break the agent's turn
+  }
+}
+
+// Hand off in-process to the real binary — it reads the subcommand from argv ("mcp" / "onboard-hook" / …).
+await import(pathToFileURL(binJs).href);

scripts/sync-plugin.mjs

@@ -21,4 +21,10 @@ const skillDest = join(root, "plugin", "skills", "devcoach", "SKILL.md");
 mkdirSync(dirname(skillDest), { recursive: true });
 cpSync(join(root, "assets", "SKILL.md"), skillDest);
 
-console.log(`synced plugin → version ${version}, SKILL.md copied`);
+// 3. Pin the published devcoach version the plugin installs at runtime (scripts/launch.mjs) to this
+//    release — same in-place regex approach, so a version bump re-triggers the launcher's npm install.
+const pluginPkgPath = join(root, "plugin", "package.json");
+const pluginPkg = readFileSync(pluginPkgPath, "utf8");
+writeFileSync(pluginPkgPath, pluginPkg.replace(/"devcoach": "[^"]+"/, `"devcoach": "${version}"`));
+
+console.log(`synced plugin → version ${version}, SKILL.md copied, devcoach pinned`);