Metadata-Version: 2.4
Name: performance-agent
Version: 0.12.0
Summary: Evidence-based AI physical preparation platform — backend
Keywords: strength-and-conditioning,training,coaching,mcp,evidence-based,sports-science
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Healthcare Industry
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Dist: fitdecode==0.11.0
Requires-Dist: mcp==1.28.1
Requires-Dist: pydantic==2.13.4
Requires-Dist: pyyaml==6.0.3
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/clementrx/Performance-agent
Project-URL: Issues, https://github.com/clementrx/Performance-agent/issues
Description-Content-Type: text/markdown

# PerformanceAgent

🏋️ **The first open-source AI Strength & Conditioning Coach powered by scientific research.**

**English** · [Français](docs/i18n/README.fr.md) · [Español](docs/i18n/README.es.md) · [Deutsch](docs/i18n/README.de.md) · [Italiano](docs/i18n/README.it.md)

![PyPI](https://img.shields.io/pypi/v/performance-agent)
![CI](https://github.com/clementrx/Performance-agent/actions/workflows/ci.yml/badge.svg)
![License](https://img.shields.io/badge/license-Apache--2.0-blue)
![Python](https://img.shields.io/badge/python-3.13-blue)
![Status](https://img.shields.io/badge/status-early%20development-orange)

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:

```text
$ 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?
```

## Why another AI fitness coach? Because this one can't lie to you

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_from` delta 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.

## Install once — then it's one folder per athlete

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:

```bash
mkdir -p ~/coaching/marie && cd ~/coaching/marie && claude
```

**Make 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.

### One-time setup (Claude Code — 2 commands)

**Never used Claude Code before?** Install it first:

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

(full instructions: [code.claude.com/docs](https://code.claude.com/docs/en/quickstart.md)).
You'll also need [`uv`](https://docs.astral.sh/uv/getting-started/installation/) — 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](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_HOME` to the
> athlete's folder in the server config instead of `cd`-ing into it.

## How to use it, step by step

1. **`cd` into the athlete's folder and start your agent** (`claude`) — an empty
   folder for a new athlete, an existing one to pick up their history.
2. **Say your goal in plain language** — any language works. *"I want to run a 10K
   under 50 minutes"*, *"Prépare-moi pour un Hyrox"*.
3. **Answer the coach's questions.** First time, it runs a short onboarding (current
   level, history, schedule, equipment) and saves your profile.
4. **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.
5. **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.html` is 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](https://github.com/hasaneyldrm/exercises-dataset),
   cloned automatically in the background at server start.)
6. **After each workout, log it in one line** — *"Logged: 8 km easy, RPE 4"*.
7. **Every couple of weeks, say "Check-in"** — the coach compares plan vs. reality,
   quotes your training load, and flags drift.
8. **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.

## Three real examples

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/`](examples/), in all five languages.

### 1. Run a 10K under 50 minutes

```text
> 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.
```

### 2. Prepare a Hyrox in 3 months

```text
> 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
```

### 3. Visible abs and bigger arms in 3 months

```text
> 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
```

## Which AI tool can I use this with?

The **MCP server** (engine, science, data) speaks a standard protocol —
[MCP](https://modelcontextprotocol.io) — 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 | ⚠️ paste into `GEMINI.md` |
| Codex | ✅ native | ⚠️ paste into `AGENTS.md` |
| Cursor | ✅ native | ⚠️ paste into `.cursor/rules/*.mdc` |
| Windsurf | ✅ native | ⚠️ paste into its rules/memories settings |
| VS Code (GitHub Copilot) | ✅ native | ⚠️ paste into `.github/copilot-instructions.md` |
| Cline (VS Code extension) | ✅ native | ⚠️ paste into `.clinerules/` |

Setup commands for each, PDF reports (requires `typst`), data-directory resolution,
and troubleshooting: [docs/installing.md](docs/installing.md). Any other tool that
supports MCP servers works with the same `uvx performance-agent` command.

## What it does

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.

### Roadmap

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.

## How it works

Just here to use the coach? Skip this — it's for the curious and for contributors.

```mermaid
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**.

## Design principles

- **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.

## For developers

The engine is a pure Python package you can use directly:

```python
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 rates
```

Repository layout: `src/performance_agent` (engine, evidence, memory, reports, MCP
server) · `skills/` (coaching protocols) · `docs/` (install & usage) ·
`examples/` (full sample conversations in five languages).

## Contributing

Early development, moving fast — see [CONTRIBUTING.md](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.

## License

Apache-2.0 — see [LICENSE](LICENSE).
