🏋️ The first open-source AI Strength & Conditioning Coach powered by scientific research.
English · Français · Español · Deutsch · Italiano
It runs inside an AI agent CLI — a terminal program you chat with, such as Claude Code, Gemini CLI, or Codex — and turns it into a professional coach that designs, explains, monitors, and adapts your training. No backend, no API key, no hosting, no extra subscription. And it will tell you the truth when your goal is unrealistic:
$ claude
> I run 10K in 55:00. I want 35:00 in 12 weeks.
🏋️ Coach: I evaluated your goal with the feasibility engine:
Probability: 0.2% — I have to be honest, this is unrealistic.
You're asking for a 36% improvement — about 3%/week sustained
for 12 weeks. Beginners sustain roughly 1%/week.
Counter-proposal: 46:30 in 12 weeks (~78% probability),
then we reassess. Want me to build that program?
LLM fitness coaches have two failure modes: they invent scientific references, and they tell you what you want to hear. PerformanceAgent is architected so neither is possible:
- LLMs narrate, the engine calculates. Every number — feasibility probabilities, race predictions, training loads, periodization waves — comes from a deterministic, property-tested Python engine. The agent explains the math; it never does the math.
- Citations can't be hallucinated. The coach may only cite studies returned by the local evidence corpus (graded, DOI/PMID-verified). The PDF renderer hard-fails on any reference that isn't in the corpus.
- Your data is files, not a cloud. Profile, programs, session logs, and check-ins live in a plain directory of markdown/YAML you can read, edit, diff, and sync.
- Any sport, not a lookup table. The coach researches what determines performance in your event and fills a structured, versioned model — trainable qualities, benchmarks, injury risks — then computes your gaps against it. A kayak sprinter is modeled exactly like a powerlifter; no sport is hard-coded. Exercise choice is a deterministic scored ranking (not authored from memory), and the individualization is fitted: your own fitness-fatigue time constants, taper response and per-quality rates — with honesty gates that refuse a number when the data is too thin — planned across a 1-4 year macrocycle.
- Athlete document drop folder — drop studies, physio reports or past
programs into
documentation/; verified studies join the evidence corpus (full text read), everything else informs coaching as context, never faked as science. - Research that stays alive — targeted mini-waves on plateaus, injuries and
athlete questions; an incremental literature watch at every mesocycle
boundary (
year_fromdelta queries), all folded into the versioned dossier. - Weekly loads review — structured per-block progression rules computed by
the engine (
suggest_next_week_loads): next week's exact weights from this week's logs, flags instead of guesses. - Program watch — a biweekly per-exercise audit (keep / watch / substitute candidate) written as a versioned report; substitutions go through program-adaptation, never silently.
- Science on the gym page — the offline program HTML opens with sourced
advice and "why this program" lines,
[n]markers on blocks, and a starred bibliography. - Pre-competition protocol — the final days before any competition planned day by day (engine-computed attempts, pacing splits and carb loading; risky peak-week practices described only with evidence grade + explicit warning), delivered as a versioned document and an offline phone page for the event.
PerformanceAgent isn't an app you open — it plugs into an AI agent CLI. You set it up once (below), and from then on coaching someone is three moves:
mkdir -p ~/coaching/marie && cd ~/coaching/marie && claudeMake a folder, cd into it, launch claude — and you're coaching. That folder
is the athlete: profile, programs, session logs and check-ins all live inside it as
plain files you can read, edit, diff and back up. Nothing is sent anywhere. Coaching
several athletes is just several folders — cd into the right one and the coach picks
up where you left off. Then you talk to it in plain language; no config files, no
commands to memorize.
Never used Claude Code before? Install it first:
curl -fsSL https://claude.ai/install.sh | bash(full instructions: code.claude.com/docs).
You'll also need uv — it
fetches the right Python version by itself, nothing else to install.
Install the plugin. From inside Claude Code, run these two commands once:
/plugin marketplace add clementrx/Performance-agent
/plugin install performance-agent@performance-agent
One install gives you both halves of the coach: the tools (the engine, the science
library, your future athlete profile) as an MCP server, and the coaching protocols
— the 16 skills that tell Claude when to ask what, when to be honest about a goal, how
to build a program. The MCP server registers at user scope, so it's available from
every folder you later launch claude in — which is what makes one-folder-per-athlete
work. Claude Code keeps the plugin up to date (/plugin marketplace update performance-agent).
Fully quit and restart Claude Code. New tools and skills load only when a claude
session starts: close any open session completely and run claude again.
Check it worked — open an athlete folder and ask:
> List the performance-agent tools.
You should see 104 tools. If so, you're done — make a folder and start coaching.
Not on Claude Code? Cursor, Claude Desktop and other MCP hosts have no plugin format. Register the server manually with
claude mcp add performance-agent -s user -- uvx performance-agent(or the equivalent JSON in your host's MCP config), then copy the coaching skills into your host's instructions. Full per-client steps: docs/installing.md.
On a host that can't pick the launch folder? Claude Desktop and a few other MCP hosts always start from the same place. There, set
PERFORMANCE_AGENT_HOMEto the athlete's folder in the server config instead ofcd-ing into it.
cdinto the athlete's folder and start your agent (claude) — an empty folder for a new athlete, an existing one to pick up their history.- Say your goal in plain language — any language works. "I want to run a 10K under 50 minutes", "Prépare-moi pour un Hyrox".
- Answer the coach's questions. First time, it runs a short onboarding (current level, history, schedule, equipment) and saves your profile.
- Get an honest verdict. The feasibility engine scores your goal; if it's out of reach, you get the real probability and a counter-proposal.
- Say yes — the program is written to
programs/program-20260712.md, periodized into cycles with deloads and taper, every prescription carrying its purpose, evidence grade (★★★★★ → ★☆☆☆☆), and verified citations. Next to it,program-20260712.htmlis a standalone session page for the gym: every strength exercise with its animation GIF, step-by-step technique in your language, sets, reps, load, and rest — fully offline, send it to your phone. (Media from exercises-dataset, cloned automatically in the background at server start.) - After each workout, log it in one line — "Logged: 8 km easy, RPE 4".
- Every couple of weeks, say "Check-in" — the coach compares plan vs. reality, quotes your training load, and flags drift.
- When life happens — "I tweaked my ankle", "I can only train twice next week" — the program is adapted and versioned (nouveau fichier daté) with the reason recorded in the audit trail.
Feasibility numbers below come from the deterministic engine — run it yourself and
you'll get the same ones. Want to see the resulting program files? Each of these
three conversations ends with a full program — browse them in
examples/, in all five languages.
> I want to run a 10K under 50 minutes. I have 5 months. Coach me.
🏋️ Coach: Two facts before I judge that goal: your current 10K time,
and how long you've been training consistently?
> I ran 55:12 last month. About a year of running, 3× a week.
🏋️ Coach: Feasibility over your 21-week horizon:
Probability: 84% — realistic, and worth committing to.
You need a 9.5% improvement, i.e. 0.45%/week, while a runner at
your training age can sustain about 1%/week. Comfortable margin.
Want me to build the program?
> Yes.
📄 Program written to programs/program-20260712.md
21 weeks, 3 runs/week: one interval session, one tempo, one long
run — periodized with deloads and a 10-day taper.
> I signed up for a Hyrox in 3 months. Build me a plan.
🏋️ Coach: Hyrox is 8 km of running broken up by 8 strength stations —
so we train both, together. Three facts: your 10K time (or best
guess), your strength background, and days per week you can train?
> 10K around 52 min, I lift twice a week, I can do 4 sessions.
🏋️ Coach: Good base for a strong first finish. Honest note: 12 weeks
is enough to finish well and enjoy it; chasing a podium time would
need a longer runway — I'd rather tell you now.
Plan on 4 days: one running-interval day, one station-strength day
(sled work, lunges, wall balls), one "compromised running" brick
(run → station → run, the skill Hyrox actually tests), one easy
long run. Deloads weeks 4 and 8, race-week taper. Build it?
> Yes.
📄 Program written to programs/program-20260712.md
> I want visible abs and bigger arms in 3 months.
🏋️ Coach: Those are two different physiological goals — arms grow
with volume and enough calories; abs show at low body fat, which
usually means a deficit. Before I promise anything: height, weight,
training experience, and sessions per week?
> 1.78 m, 82 kg, two years of lifting, 4 sessions a week.
🏋️ Coach: Honest verdict: in 12 weeks you can make real progress on
both, but not maximize both — recomposition is slow at two years
of training. The realistic version:
- Moderate calorie deficit with a high protein target (the
Nutritionist skill quantifies it, with safety guards).
- Upper-body priority: 12–16 hard sets/week for arms, heavy
compound work kept in to protect strength in the deficit.
- 3 lifting days + 1 conditioning day.
- Expected at week 12: visibly fuller arms, abs "outlined" if
you start around 15–18% body fat; leaner than that takes longer,
and I'll say so at every check-in rather than let you guess.
Want the program?
> Yes.
📄 Program written to programs/program-20260712.md
The MCP server (engine, science, data) speaks a standard protocol — MCP — that most AI coding tools understand. The coaching skills are packaged in Claude Code's native skill format; elsewhere you paste the same instructions into that tool's own "custom instructions" file.
| Client | MCP tools | Coaching skills |
|---|---|---|
| Claude Code | ✅ native (steps above) | ✅ native |
| Gemini CLI | ✅ native | GEMINI.md |
| Codex | ✅ native | AGENTS.md |
| Cursor | ✅ native | .cursor/rules/*.mdc |
| Windsurf | ✅ native | |
| VS Code (GitHub Copilot) | ✅ native | .github/copilot-instructions.md |
| Cline (VS Code extension) | ✅ native | .clinerules/ |
Setup commands for each, PDF reports (requires typst), data-directory resolution,
and troubleshooting: docs/installing.md. Any other tool that
supports MCP servers works with the same uvx performance-agent command.
Everything below runs in the deterministic engine — no LLM in the numbers.
Load & readiness. 1RM estimation, Riegel race prediction, session-RPE load and ACWR, monotony/strain, fitness-fatigue CTL/ATL/TSB, readiness banding, external-load budgeting. Data-driven deload recommendations (monotony/strain, TSB and readiness trends against the planned counter) and a clearance-gated return-to-load ramp after time off.
Planning. Goal feasibility, periodization waves, backward season planning from a dated calendar, and multi-year macrocycle planning (1–4 years typed backward from the major event, per-year quality-emphasis budgets derived from the gap priorities). An intra-week sequencing and interference guard (heavy-pattern spacing, HIIT-before-lower interference, consecutive-high-day and match-window rules) and a training-residuals guard that warns where a maintained quality would decay past its Issurin retention window.
What determines performance. A sport-agnostic PerformanceModel — the
researched, versioned answer to "what makes performance in this event": trainable
qualities with normalized weights, KPIs with level benchmarks, injury risks and
energy-system split, every value provenance-labeled cited / prior / judgment. It
drives gap analysis (measured KPIs vs benchmarks, per-quality training priorities;
unmeasured stays unmeasured) and a dated test battery scheduled as experiments around
the calendar. Four reference models ship seeded (sprint, 10k, powerlifting, football)
— examples, not a support gate.
Exercise selection. A structured ontology (~120 seed exercises attributed by movement pattern, force vector, contraction regime, kinetic chain, equipment, specificity level and qualities trained — filterable and extensible with the athlete's own). Deterministic scored selection (quality match × phase-appropriate specificity × equipment feasibility × contraindication hard-gate × novelty, ranked with a per-attribute justification), stimulus-equivalence substitution, and a mesocycle specificity-mix guard.
Individualization. Recalibration from the athlete's own logs — measured progression rate honest about n, prescribed-vs-actual compliance, volume-tolerance association, a versioned response profile — which recomputes goal feasibility against the measured rate. Plus a fitted two-component Banister impulse-response model (pure Python grid fit of fitness/fatigue time constants and gains; refused without ≥8 weeks of load and ≥5 spanning performance points, or when pinned/implausible) and individual taper response (detects past tapers, pairs each with its event-linked outcome, recommends from the athlete's own best-outcome taper when ≥2 exist — else the labeled population rule).
Day of. Session autoregulation (readiness-based adjustment, time compression, exercise substitution) and velocity-based load suggestions — bounded, labeled, never auto-applied — fed by load-velocity profiling (a fitted per-exercise velocity-load line with an estimated 1RM, refused when the loads are too few or too narrow).
Data in. Activity-file import (.fit/.tcx/.gpx/CSV, incl. power/cadence/splits and VBT exports) proposes a session for the athlete to confirm before logging — or pulls straight from Garmin/Strava when their MCP server is connected. High-resolution inputs are all optional: VBT CSVs land as structured sets, rides yield power/normalized-power/cadence/lap-splits, jump/sprint measurements land in the KPI log. Missing data lowers the stated resolution rather than blocking.
Recovery. Device trends read deterministically by a dedicated recovery-analyst skill: rolling ln-rMSSD vs a 28-day baseline ± the smallest worthwhile change, resting-HR and sleep-debt trends, honesty-gated.
Evidence. DOI/PMID/ISBN-verified corpus with anti-fabrication citation checks, live search (PubMed, OpenAlex, Crossref, Semantic Scholar) behind a double verification gate, and Typst PDF reports (en/fr/es) behind a hard citation gate.
Memory & follow-up. File-based athlete memory: season calendar, pre-session readiness logs, versioned machine-readable programs (structured plan + rendered markdown), a day-of adjustment log with escalation signals, a versioned response profile, versioned performance models, a dated KPI-results log, and an adaptation audit trail. Proactive follow-up surfaces what is due (overdue check-in, imminent race, missed sessions, readiness gaps, a stale response profile) severity-ordered, so the coach speaks first.
Proof it composes. A deterministic end-to-end simulation (no LLM) drives the real engine and store across synthetic athletes — including an unseeded sport (kayak sprint) whose hand-authored model flows through the whole pipeline exactly like a seeded one, showing the machine is sport-independent.
104 MCP tools · 16 coaching skills incl. a mandatory delivery gate with an adversarial second opinion · 1444 tests, incl. property-based.
Environment & fine peaking (altitude/hypoxia, heat acclimatization, jet-lag protocols, competition-hour scheduling) — the deliberate next iteration · corpus growth toward ~200 studies · outcome simulation (Monte Carlo on the fitted Banister model) · optional web front-end reusing the same MCP server.
Just here to use the coach? Skip this — it's for the curious and for contributors.
flowchart TB
U[You] <--> H[Your agent CLI<br/>Claude Code · Gemini CLI · Codex<br/>= the coach: converses, reasons, adapts]
H <-->|MCP| S[performance-agent server]
H -.follows.-> SK[Coaching skills<br/>onboarding · needs analysis · deep research ·
planning · optimization · nutrition · review · check-ins · session-day · adaptation]
S --> E[Sports science engine<br/>deterministic · property-tested · zero LLM]
S --> EV[(Evidence corpus<br/>graded studies, SQLite FTS5)]
S --> M[(Athlete directory<br/>profile · programs · logs — plain files)]
S --> R[Typst PDF reports<br/>coach & expert modes · en/fr/es]
The skills encode professional coaching protocols (what to ask, when to be honest, how to periodize, when to deload). The MCP tools own every fact. The agent you already use glues it together with your existing subscription — zero additional LLM cost.
- Evidence first — systematic reviews → meta-analyses → RCTs → cohorts → expert opinion; every recommendation shows its grade, and thin evidence is labeled as such.
- Honest by construction — unrealistic goals get honest probabilities with the drivers behind them; contested metrics carry their caveats.
- Agent-native — your CLI agent is the interface; your subscription is the compute; your filesystem is the database.
- Long-term athlete memory — no conversation starts from zero.
The engine is a pure Python package you can use directly:
from performance_agent.engine import TrainingAge, endurance_feasibility
verdict = endurance_feasibility(
current_time_s=3300, target_time_s=2100, weeks=12, training_age=TrainingAge.BEGINNER
)
verdict.probability # 0.0023 — with improvement_needed, required and achievable ratesRepository layout: src/performance_agent (engine, evidence, memory, reports, MCP
server) · skills/ (coaching protocols) · docs/ (install & usage) ·
examples/ (full sample conversations in five languages).
Early development, moving fast — see CONTRIBUTING.md for the dev setup and review conventions. Sports scientists and S&C coaches: the evidence-grading pipeline will need expert reviewers — watch this space.
Apache-2.0 — see LICENSE.