# claude-engineering-coach

**A native Claude Code plugin** that coaches you on your AI-assisted coding —
without leaving the Claude Code terminal. Get usage summaries, anti-pattern
coaching, tool comparisons, and flow analysis via MCP tools and `/coach:*`
slash commands. (It can still read Codex / OpenCode / Copilot sessions too, but it
**runs inside Claude Code**.)

Local-only · read-only · zero telemetry.

> Reuses the analytics core of Microsoft's
> [AI Engineering Coach](https://github.com/microsoft/ai-engineering-coach) — but that
> is a **VS Code / GitHub Copilot** extension. **This one is built for Claude Code:** it
> ships as a Claude Code plugin, so the coaching lives where you already work.
> MIT-licensed. **Not affiliated with, sponsored by, or endorsed by Microsoft.** See `NOTICE`.

---

## What it does

It reads your on-disk AI session logs (e.g. `~/.claude/projects/**/*.jsonl`) and
turns them into actionable coaching:

- **`/coach:summary`** — sessions, output, and your top anti-patterns
- **`/coach:improve`** — prioritized, evidence-backed recommendations
- **`/coach:compare`** — your AI tools side-by-side (sessions, LOC, models, cancel rates)
- **`/coach:flow`** — deep-work scores, best hours, session continuity

Claude can also call the underlying tools on its own — just ask *"how was my
coding this week, and what should I improve?"*

Nothing leaves your machine: the server parses your logs in-process, redacts
secrets before any output reaches the model, and never writes to your session
files.

---

## Install

Requires **Node ≥ 18** (the bundled MCP server runs with `node`). No `npm install`
needed — the server bundle and rule assets are committed.

### Easiest — install straight from GitHub (no local path)

In an interactive Claude Code session:

```text
/plugin marketplace add nnhhoang/claude-engineering-coach
/plugin install coach@devempower-coach
/reload-plugins
```

Here `marketplace add` points at the **GitHub repo** (`owner/repo`), so there is
no folder path to fill in. The marketplace name `devempower-coach` is read from
`.claude-plugin/marketplace.json`; you use it in the `install coach@devempower-coach`
step. Choose a scope when prompted (Local is fine for yourself).

### Local dev — clone and load directly

```bash
git clone https://github.com/nnhhoang/claude-engineering-coach.git
cd claude-engineering-coach
claude --plugin-dir .
```

The `.` means "this folder" — nothing to fill in. Loads the plugin (commands +
MCP server) for that session only.

> Note: an earlier draft showed `/plugin marketplace add /path/to/claude-engineering-coach`.
> That `/path/to/...` was just a **placeholder** for "wherever you cloned it" — the
> two methods above avoid it entirely (one uses `owner/repo`, the other uses `.`).

### Verify

```text
/mcp
```

You should see the **`coach`** server connected with **13 tools**. Then run:

```text
/coach:summary
```

---

## MCP tools (13)

`coach_summary`, `coach_activity`, `coach_credits`, `coach_codeProduction`,
`coach_flow`, `coach_patterns`, `coach_insights`, `coach_wellbeing`,
`coach_workflows`, `coach_harnessComparison`, `coach_sessions`,
`coach_contextHealth`, and `coach_reload` (re-read logs after new sessions).

When no date range is given, tools default to the **last 90 days**. Pass
`fromDate` / `toDate` (ISO `YYYY-MM-DD`) to widen or narrow.

---

## How it works

```
core/                vendored analytics (parsers, analyzers, 45 rule + 10 metric .md)
  └─ formatters.ts   pure formatter functions
mcp/
  ├─ tool-defs.ts    12 tools (+ 90-day default + secret redaction)
  ├─ analyzer-cache.ts  lazy, cached Analyzer over parseAllLogs(findLogsDirs())
  ├─ server.ts       MCP stdio server (list / call / reload)
  └─ dist/server.mjs committed esbuild bundle (+ rules/ + metrics/ assets)
commands/            /coach:summary · improve · compare · flow
.claude-plugin/      plugin.json + marketplace.json
.mcp.json            registers the bundled "coach" server
```

The analytics engine is reused verbatim from upstream (it was already VS Code-free).
Only the integration layer (`mcp/`) and packaging are new.

### Rebuild after changing `mcp/**` or re-vendoring `core/`

```bash
npm install   # first time only
npm run build # → mcp/dist/server.mjs (+ copies rule/metric assets)
npm test      # core-smoke, tool-defs, analyzer-cache, server.e2e
```

The build commits its output (`mcp/dist/`) so the plugin runs on a fresh clone
with only `node`.

---

## Attribution & license

This project vendors the analytics core of
[microsoft/ai-engineering-coach](https://github.com/microsoft/ai-engineering-coach)
(MIT). Vendored files under `core/` keep their original Microsoft copyright
headers; see `NOTICE` and `VENDOR.md` for the exact upstream commit.

Licensed under the [MIT License](LICENSE). Not affiliated with Microsoft.