claude-hevy-coach

Claude as your personal strength coach, wired into the Hevy 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 (Claude Desktop works too — see below)

Setup (~3 minutes)

1. Get the code and install:

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

2. Add your Hevy API key:

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:

npm run doctor

You want: ✅ Hevy API key works.

4. Start coaching:

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 — 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:

{
  "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