hevy-mcp: Instructions file for Codex

AGENTS.md

Instructions for AI coding agents working in this repository. This file is the single source of truth; CLAUDE.md and .github/copilot-instructions.md only point back here. Subdirectories with rules of their own carry a nested AGENTS.md — read it when you touch that directory.

What this project is

hevy-coach-mcp is an MCP server that gives an AI assistant access to a user's Hevy training log, and computes the analytics on top of it: estimated 1RM, PRs, volume per muscle group, consistency, period-over-period comparison.

The guiding principle, which explains most of the design: the server computes the numbers, the model makes the judgements. All arithmetic lives in src/engine/ as a pure library, tested against fixtures, with no I/O. The assistant never does maths on training data — it interprets results it was handed. If you find yourself moving a calculation into a tool description or expecting the model to add things up, you have broken the core contract.

Requires Hevy PRO, which is what unlocks Hevy's API.

Validate your changes

There is no linter and no formatter in this repo. yarn lint does not exist — do not run it. A change is validated when all three of these pass:

yarn typecheck   # tsc --noEmit
yarn test        # vitest run
yarn build       # rm -rf dist && tsc -p tsconfig.build.json

Run all three before you call any task finished. CI (.github/workflows/ci.yml) runs exactly the same three, then packs the tarball and asserts what is inside it: that dist/stdio.js is present and still has its shebang, and that no compiled test or dist/store/ came along. That step needs nothing from you locally — it guards a mistake that is invisible until someone opens the published package.

CI has a second job, changeset, which fails when a pull request adds no changeset. It is not a required check, because docs-only and chore branches have nothing to announce: add the changeset, or label the pull request no-changeset.