# claude-hevy-coach

Claude as your personal strength coach, wired into the [Hevy](https://hevy.com)
app.

Say **"coach me"** → Claude reads your real lifting history, checks how your
last programmed workout actually went, asks how you're feeling, designs your
next session, and writes it into Hevy as a routine. At the gym you just open
Hevy and tap **Start**.

## What you need

- **Hevy Pro** — the Hevy API key requires it
- **Node.js 20+** — <https://nodejs.org>
- **[Claude Code](https://claude.com/claude-code)** (Claude Desktop works too — see below)

## Setup (~3 minutes)

**1. Get the code and install:**

```bash
git clone https://github.com/jmilinovich/claude-hevy-coach.git
cd claude-hevy-coach
npm install
```

**2. Add your Hevy API key:**

```bash
cp .env.example .env
```

Get your key at <https://hevy.com/settings?developer> and paste it into `.env`
so it reads:

```
HEVY_API_KEY=your-key-here
```

**3. Check it works:**

```bash
npm run doctor
```

You want: `✅ Hevy API key works.`

**4. Start coaching:**

```bash
claude
```

When Claude Code asks to use the `hevy-coach` MCP server, approve it. Then
just say:

> coach me

That's it. The first time, Claude interviews you for a couple of minutes (goals,
schedule, equipment, injuries, your working weights) and saves your profile.
Every time after: it recaps your last session, programs the next one, shows you
the card, and — once you say go — writes it to Hevy. Open the Hevy app and tap
**Start** on the **🤖** routine.

## Day to day

Things you can say:

- *"coach me"* / *"program my next workout"*
- *"push day, 45 minutes, easy on the shoulders"*
- *"how did my last session go?"*
- *"how's my bench trending?"*
- *"I tweaked my knee — work around it"* (it'll update your profile too)

Your training philosophy lives in [`COACH.md`](COACH.md) — edit it any time,
the coach reads it fresh before every session. Your block position, baseline
loads, and prescription history live in `state/` (local only, not committed).

## Using Claude Desktop instead

Do your **first conversation in Claude Code** (the setup interview writes your
profile into `COACH.md`, which Claude Desktop can't edit). After that, Desktop
works great for day-to-day coaching.

Add this to `claude_desktop_config.json` (Settings → Developer → Edit Config),
replacing both paths with wherever you cloned the repo:

```json
{
  "mcpServers": {
    "hevy-coach": {
      "command": "/ABSOLUTE/PATH/TO/claude-hevy-coach/node_modules/.bin/tsx",
      "args": ["/ABSOLUTE/PATH/TO/claude-hevy-coach/src/mcp/server.ts"]
    }
  }
}
```

(That's the repo's own `tsx` binary — Desktop launches servers from outside the
repo folder, so a bare `npx tsx` wouldn't find it.) Restart Claude Desktop,
then tell it: *"You're my strength coach — start with the
get_programming_brief tool."* Claude Desktop doesn't read `CLAUDE.md`, so that
first nudge points it at the brief, which carries the coaching instructions.
One limitation: profile updates ("my gym has no cables now") need `COACH.md`
edited — do those in Claude Code, or edit the file yourself.

## How it works (60 seconds)

- **The Hevy API has no scheduler and no deletes** — the only way to hand you a
  planned workout is to overwrite a routine. So the coach maintains exactly
  **one** routine, marked `🤖` (the default marker), rewritten in place each
  session.
- **`COACH.md` is the doctrine** — your goals, split, equipment, injuries, and
  effort rules, in plain English. It's injected into every programming brief.
- **The engine derives everything from your history** — which day is due,
  whether it's a deload, what loads to prescribe. The only stored state is a
  tiny block seed, your baseline loads, and an append-only log of what was
  prescribed (`state/`, gitignored).
- **The learning loop**: Hevy records what you *did*; the coach records what it
  *prescribed*. Before each session it diffs the two — held / heavier /
  lighter / faded / skipped — and adjusts.
- **Workout writes are previewed first.** `commit_workout` validates against
  your live exercise catalog, shows you the card, and only writes after you
  approve (creating a custom exercise also waits for your explicit OK).
  Everything runs locally; the only network calls are to `api.hevyapp.com`.

## Troubleshooting

| Symptom | Fix |
|---|---|
| `npm run doctor` says key rejected | Re-copy the key from <https://hevy.com/settings?developer>; make sure your Hevy Pro subscription is active |
| Claude says it has no hevy-coach tools | Run `/mcp` in Claude Code and approve the server; make sure `npm install` ran; restart Claude Code in this folder |
| `npx tsx` not found | Run `npm install` in the repo folder first |
| Coach programs movements your gym doesn't have | Tell it — it updates `COACH.md` and won't do it again |
| On Windows the server won't connect | Edit `.mcp.json` to `{"command": "cmd", "args": ["/c", "npx", "tsx", "src/mcp/server.ts"]}` (native Windows needs the `cmd /c` wrapper; WSL doesn't) |
| You want a fresh start | Delete the `state/` folder contents **and** run `git checkout COACH.md` (restores the template) — the coach re-interviews you next time |

## License

MIT