trainctl MCP server
Commit Nov 14, 2026Lets an AI agent act as a research-backed running coach by managing training plans as code in a git repository.
Also known as dithiothreitol/trainctl
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- MIT
What is trainctl MCP?
trainctl lets an AI agent act as a research-backed running coach by managing training plans as code in a git repository.
Summary generated from the project's README
About trainctl MCP server
Managing a running training plan as code is what trainctl enables for athletes and developers using AI agents. By storing training data in a git repository as YAML files, users can treat their fitness progression like a software project, utilizing branches, diffs, and version control. The system works locally on your machine using Node, requiring no external database or backend, and relies on your existing git history to track progress.
Running coaches or athletes can connect an MCP client like Claude Code to the server to act as a research-backed training partner. The engine uses a coaching corpus to generate plans that include specific session purposes and scientific rules. Users can manage their schedule through commands like plan, log, and reschedule, while the adapt tool proposes corrections based on actual performance. It integrates with existing data through the pull command to import files from Strava or watch exports.
What you can do with it
- 1Adjust schedules for busy weeksRe-solve your weekly training plan around specific days you are unavailable to ensure the training stimulus remains effective.
- 2Analyze training executionCompare your completed workout data against the original targets to propose necessary plan adjustments.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
TRAINCTL_DIRTRAINCTL_INTERVALS_API_KEYTRAINCTL_LANG
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabledithiothreitol/trainctl is public and reachablegithub.com/dithiothreitol/trainctl ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/dithiothreitol/trainctl ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubtrainctl
New in 0.9.0: a running engine checked against a coaching corpus (season
shape, a long-run track, accents that progress, a return after a break), season,
week and day views on one row layout, review against each workout's targets
from laps, miles and a heart-rate ceiling as view options, and the session plan
as the default model, on par with the running plan.
Release notes.
trainctl init --agent claude # profile + plugin setup for your agent
trainctl pull --from ~/exports # what you ran, from watch or Strava export files
trainctl plan # regenerates the future, keeps what you decided
trainctl status # one screen: profile, plan, key, sync, proposals, git
plan on an existing plan keeps past and logged days, pins, hand edits and the
volume baseline you approved. Every command takes --json, -C <dir> and
relative dates such as tomorrow or sat. See the changelog.
A running coach that lives in your terminal. A plan-generating engine with a CLI and an MCP server: your training plan is a YAML file in a git repository, every session cites the research behind it, and your agent (Claude Code, Codex, any MCP client) gets the coach as a tool.
$ trainctl today
2026-08-04 · Tuesday
week 1/17 · base · 117 days to race
────────────────────────────
╭─ intervals · 8 km ───────────────────────────────────────────────────────────
│ 3 km warm-up + 4 × 1 km @ 4:32/km, 2 min walk recovery. 1 km cool-down jog
│ to finish.
╰──────────────────────────────────────────────────────────────────────────────
→ why this session: trainctl why --date 2026-08-04
No account, no database, no backend. Everything is files in the current
directory — trainctl.yaml, plan/, log.jsonl — so the history of your
training is your git history.
Polska wersja: README.pl.md.
Contents · Install · Quick start · The daily loop · Commands · Configuration · Plan as code · Agent (MCP) · Watch sync and export · Language · How it decides · Where it refuses · FAQ · Development
Install
Version 0.9.0 is available on GitHub Releases.
Download the bundled CLI/MCP and Codex plugin ZIP and follow INSTALL.txt.
All six packages are also available on npm at 0.9.0; latest points to this version.
npx trainctl init # no install at all
# or
npm install -g trainctl # then just: trainctl
Node ≥ 22.18 is the only requirement. The package ships compiled JavaScript
next to its TypeScript sources and source maps, so a stack trace still points at
readable code — Node refuses to strip types under node_modules, which is why
0.1.0 was replaced by 0.1.1.
Quick start
1 · Make a training directory and a profile.
mkdir my-training && cd my-training && git init
trainctl init # interactive wizard
trainctl init --template # or: write trainctl.yaml and edit it yourself
init also drops an AGENTS.md into the directory (coach instructions for your
agent) and adds .env, .env.* and .trainctl-secret to .gitignore — the
places an API key is allowed to live.
2 · Fill in the profile. The minimum is your recent volume, the days you can train, and one race result — zones come from races, never from a watch's threshold estimate:
athlete:
recentWeeklyKm: 45 # average of the last ~4 weeks
peakWeeklyKm: 65 # highest volume you have held (optional)
daysAvailable: [tue, wed, thu, sat, sun]
longRunDay: sat
results:
- { date: "2026-03-29", distanceKm: 10, timeSec: 2580, name: "Spring 10K" }
goal:
name: "Half marathon"
date: "2026-11-29"
distanceKm: 21.0975
priority: A
3 · Generate the plan.
$ trainctl plan
Half marathon · 21.0975 km
2026-11-29 · 17 weeks of plan
──────────────────────────────────
Volume peak 52 km/week
Recommended for this distance 42 km/week
VDOT 47.7 (from a race result)
╭─ Predicted finish ───────────────────────────────────────────────────────────
│ 1:32:24 – 1:38:07 (method: vdot)
│ Always a range, never a single number (W-1).
╰──────────────────────────────────────────────────────────────────────────────
Structure
• base: weeks 1–6
• build: weeks 7–12
• peak: weeks 13–15
• taper: weeks 16–16
• race week: weeks 17–17
✓ Saved plan/plan.yaml + plan/PLAN.md
→ trainctl today · trainctl week · trainctl why
plan/plan.yaml is the source of truth — machine-readable, hand-editable.
plan/PLAN.md is the same plan rendered for humans, so GitHub shows a readable
table on the repo page.
4 · Commit it.
git add -A && git commit -m "training plan: half marathon, 29 Nov"
From here the plan behaves like any other code: branches, diffs, review, CI.
The daily loop
$ trainctl week
Week 1/17 · from 2026-08-03
base (pyramidal) · target 49 km · planned 41 km
───────────────────────────────────
DAY DATE KM WORKOUT
Mon 08-03 — rest
Tue 08-04 8 km 3 km warm-up + 4 × 1 km @ 4:32/km, 2 min walk recovery. 1
km cool-down jog to finish.
Wed 08-05 — rest
Thu 08-06 9 km 5 km easy + hills: 15 × 200 m (relaxed). 1 km cool-down jog
to finish.
Fri 08-07 — rest
Sat 08-08 17 km 17 km very easy.
Sun 08-09 7 km 3 km warm-up + 3 km progression run (5:01 → 4:32/km). 1 km
cool-down jog to finish.
Ask why, before you trust it. Every session carries its purpose and the rule IDs behind it:
$ trainctl why --date 2026-08-04
Why this session · 2026-08-04
phase: base (pyramidal)
─────────────────────────────────────
╭─ intervals ──────────────────────────────────────────────────────────────────
│ Interval session — the stimulus follows the phase: around threshold
│ (pyramidal) or VO₂max (polarized).
╰──────────────────────────────────────────────────────────────────────────────
Rules
• I-1 — base/build: a pyramidal distribution — plenty of easy running, accents
around threshold (Casado 2022; Knopp 2024)
• I-7 — ≥48 h between quality sessions — the hard day / easy day principle
(Casado 2022)
• I-8 — two accents a week at ≥4 sessions, one at 3 (Casado 2022)
• P-1 — load undulates rather than climbing in a line — undulating progression
gave +22% VO₂max vs +11% linear (RCT Costa 2019)
→ sources and parameters: docs/science/FOUNDATIONS.md §10
Record what actually happened.
trainctl log # in a terminal: pick the session, answer a few questions
trainctl log --km 8 --time 41:20 --rpe 4 --note "felt good"
trainctl log --date yesterday --status skipped --note "work"
trainctl log --date -10 --to yesterday --status skipped --reason illness # a break
After a recorded break, trainctl adapt --prepare proposes how to come back:
about half the earlier volume, the first week easy after illness (R-5) or the
first block easy after any other break (R-11), then the plan grows back. An
injury gets no volume proposal; that decision belongs to you and a specialist.
Dates accept YYYY-MM-DD, today/tomorrow/yesterday, +N/-N and weekday
names (thu). log, review, adapt and pull look back; everything else
looks ahead. Give a break logged in advance as a date or +N
(--date +2 --to +4): --date fri in log is the last Friday.
--rpe is the session effort on the 1–10 scale. The engine stores it and the
weekly review quotes it back verbatim — it never turns feelings into zones,
paces or volume (that refusal is deliberate; see Where it refuses).
The trail exists so that a conversation — with your coach-agent or with yourself
in three weeks — starts from what you actually said at the time.
Renegotiate the week when life gets in the way. shift swaps two sessions;
reschedule re-solves the whole week around days you cannot train, and says out
loud what it sacrificed:
$ trainctl reschedule --block 2026-08-06 2026-08-08
Week renegotiation · from 2026-08-03
blocked: 2026-08-06, 2026-08-08
────────────────────────────────────────────
DAY DATE BEFORE AFTER
Mon 08-03 — —
Tue 08-04 intervals intervals
Wed 08-05 — long run
Thu 08-06 hills —
Fri 08-07 — —
Sat 08-08 long run —
Sun 08-09 tempo tempo
What changes
• long: 2026-08-08 → 2026-08-05
• dropped: easy_hills from 2026-08-06 — ran out of days — an easy session costs
least (volume, not stimulus)
• trade-off: long run outside its preferred day (Wednesday)
⚠ We do not make up the dropped kilometres on the following days — piling volume
on after a missed session works against the progression (P-1/P-3).
→ this is a preview; apply with: trainctl reschedule --apply (same --block)
Nothing is written until you pass --apply — and then it is a diff you can read
before committing.
Once a week, take stock. trainctl review is the Monday ritual in one call:
what you did, what it means, what is ahead (it pulls from intervals.icu first if
a key is configured). With laps from the watch it sets each interval session
against its targets: how many reps match the plan, their paces and how many fell
within the target range; auto laps every kilometre are named as "no laps
matching the plan" instead of being guessed. Easy and long runs get their
average pace against the easy range. Heart rate is not judged. When the reps of
the last two interval sessions run faster than the target, it suggests a fresh
result: the next tune-up race or a time trial. trainctl adapt
compares execution with the plan and proposes corrections; it never rewrites
the plan behind your back.
Commands
| command | what it does | key flags |
|---|---|---|
init |
profile wizard | --template, --from-intervals, --agent claude|codex|all, --commit |
plan |
generate the plan; on an existing plan regenerate only the future | --date, --fresh, --commit |
today |
the session for today: structure with targets, time, next session | --date, --full |
week |
the week, one row per session, with journal status | --date, --full, -i (arrow-key browsing) |
season |
the season grid, one row per week: phase, km, accents, long run | --date |
why |
purpose + research rules behind a session | --date |
log |
record a completed session (no flags in a terminal: asks) | --status, --km, --time, --test-time, --rpe, --note, --commit |
shift |
swap two sessions inside a week | --from, --to (or pick from a list), --commit |
reschedule |
re-solve the week around busy days | --block, --time, --pin, --preparation, --strategy, --apply, --commit |
replace |
Replace a session across running, cycling and swimming; preview and --apply <id> |
|
migrate |
Review migration of a running plan to session schema v2, preserving originals | |
adapt |
analyse execution, propose corrections | --date, --prepare, --apply <id>, --commit |
shorten |
fit one session into the time you have, as a proposal | --minutes, --date, --apply <id>, --commit |
review |
pull + adapt + week in one call | --days, --date, --prepare |
desk |
training windows around office hours | --heavy |
push |
send planned sessions to intervals.icu | --days, --from, --to |
pull |
fetch activities and wellness, compare | --days, --date, --from <export folder> |
export |
.fit, .ics, printout, race pack |
--what, --date |
diff |
what a regeneration would change | --plan <file> |
check |
lint the plan; fails the exit code | --strict |
status |
the directory at a glance: profile, plan, key, data, proposals, git | |
rules |
every engine rule with its source class, or one in full | [id] |
completion |
shell completion script | bash, zsh, fish, pwsh |
Every command takes --lang en|pl, --json (prints { code, data, output } —
the same data the MCP tools return) and -C <dir> (or TRAINCTL_DIR) to work
on a training directory elsewhere. trainctl help <command> prints the full
flag list with examples. Exit codes: 0 success, 1 error or refusal, 2 usage
error (unknown command or flag, a date that is not a date).
--commit commits exactly the files the command changed — never .env,
.trainctl-secret or sync.json, and never other changes you have staged.
TRAINCTL_TODAY=YYYY-MM-DD simulates the date for trying a scenario; every
output then starts by saying so, and past-day protection follows the simulated
date.
Configuration
trainctl.yaml is the whole configuration — one file, in your repository.
trainctl init --template writes it with comments; every key it supports:
schemaVersion: 2
# language: pl # interface and plan language: en | pl (default: en)
# units: imperial # miles and pace per mile in views; files stay in km (default: metric)
# notation: club # Polish club codes (OWB1, WT, BNP…) in Polish output (default: neutral)
athlete:
sports:
run:
weeklyMinutes: 270 # running time per week for the overview; with other sports, the running budget
sessionsPerWeek: 5 # with other sports: runs per week (the running engine picks them from kilometres)
daysAvailable: [tue, wed, thu, sat, sun]
preparationMinutes: 15 # getting ready and travel, counted in the calendar
results: # zone calibration — from races, not from a watch
- { date: "2026-03-29", distanceKm: 10, timeSec: 2580, name: "Spring 10K" }
running: # the running engine: kilometres, zones, rules with sources
sex: unspecified # male | female | unspecified (the heart-rate ceiling needs it)
# hrMax: { bpm: 190, measured: true } # adds a heart-rate ceiling to easy and long runs; pace stays the target
recentWeeklyKm: 45 # average of the last ~4 weeks
peakWeeklyKm: 65 # highest volume you have held (optional)
# returning: { since: "2026-10-01", previousWeeklyKm: 45 } # after 2+ weeks off: restart at about half (R-11)
longRunDay: sat
tuneUpRaces: # races on the way: B = mini-taper, C = run through
- { date: "2026-09-19", distanceKm: 10, name: "Autumn 10K", priority: B }
strength: # optional strength track, 2×/week
enabled: true
days: [mon, fri] # optional preference
goal:
kind: race
sport: run
name: "Half marathon"
date: "2026-11-29"
distanceM: 21097.5 # metres: 5000 / 10000 / 21097.5 / 42195
targetTimeSec: 5700 # optional — plan will judge how realistic it is
desk: # for trainctl desk (optional)
workStart: "09:00"
workEnd: "17:00"
lunchMinutes: 45
prefer: evening # morning | lunch | evening
time: # optional: the minutes you actually have, preparation included
weeklyMinutes: 300 # volume levels off at what fits (E-2)
weekdayMinutes: 60 # longer sessions are shortened, with the trade-off shown (E-1)
weekendMinutes: 120
sync:
files: ./activities # optional: exported FIT/TCX/GPX instead of intervals.icu
This is the session-plan layout (schema 2), which init writes since 0.9. A
running-plan profile from earlier versions (athlete.recentWeeklyKm,
athlete.results, goal.distanceKm) still works; trainctl migrate --prepare
moves it to this layout with every field and keeps the originals. The examples
below use the shorter running-plan keys; in this layout they sit under
athlete.sports.run (results, daysAvailable) and athlete.sports.run.running
(the rest).
No race to train for? Use a base plan instead of goal with a date and
distance — no taper, no prediction, volume grows to your peak and levels off (P-11):
goal:
kind: base
until: "2027-03-01"
A few consequences worth knowing:
resultsdrives everything. Without a race result there is no VDOT and no zones; with atargetTimeSecbut no result,planwill use the goal to derive zones and say clearly that it needs recalibration.tuneUpRacesare treated as races, not as workouts: mini-taper before a B race, an easy day before it, the long run the day after, and no extra accent in that week.strengthis a separate track, not a running session: it adds no kilometres, disappears during the taper, and never lands the day before a hard session. Two weeks of getting into it, then heavy sessions, and one maintenance session a week in the peak (F-18, F-4, F-12). Log it withtrainctl log --strength done. The justification is running economy — not injury prevention; see Where it refuses.- The plan does not stop at the race. After a half marathon or longer, two transition weeks follow: about half the pre-race volume, easy only, first run on the third day after a marathon; then back to normal with one accent (R-8, from three races in the coaching corpus). A new goal starts its cycle after them.
The intervals.icu API key never goes in this file. Use
TRAINCTL_INTERVALS_API_KEY, a .env file or .trainctl-secret; an explicit
environment variable wins over a file.
Plan as code
The plan is a YAML file in a git repository — and that changes what a plan can do, not just where it is stored.
What-if branches. A scenario lives on a branch or in a copied directory: change the race date there, regenerate there, then compare before you decide.
git switch -c what-if-december
sed -i 's/2026-11-29/2026-12-20/' trainctl.yaml && trainctl plan
git switch main
git show what-if-december:plan/plan.yaml > /tmp/scenario.yaml
trainctl diff --plan /tmp/scenario.yaml
Differences: current plan → /tmp/scenario.yaml
──────────────────────────────────────────────────────────────────────────────
• goal: Half marathon, 21.1 km, 2026-11-29 → Half marathon, 21.1 km, 2026-12-20
• ~ 2026-11-01: quality_continuous — same volume, different segments
• ~ week 2026-11-23: total of the days 16 → 52 km
• ~ 2026-11-24: easy → quality_intervals
• ~ 2026-11-29: race → long
• + week 2026-11-30: new (52 km)
• + week 2026-12-14: new (26 km)
Three extra weeks of build, a taper that lands three weeks later, and the race day that is no longer a race — all before anything is decided.
CI on your own training. trainctl check lints the plan against the
engine's invariants — 48 h between accents, taper shape, strength adjacency,
≥75% easy volume — plus the file's internal consistency, each finding with its
rule ID:
$ trainctl check
✓ No issues: 17 weeks and 66 sessions hold every invariant.
$ trainctl check --strict # in CI: warnings fail too, exit code 1
Plan lint
invariants and file integrity, checked against plan/plan.yaml
─────────────────
Rule deviations
⚠ 2026-08-04 → 2026-08-05: intervals and tempo less than 48 h apart [I-7]
0 errors, 1 warning
strict mode: warnings count as failures
Errors always fail the exit code; warnings only under --strict. A ready
workflow: docs/examples/ci-check.md.
A human coach as reviewer. Week changes are diffs, so a coach can review them the way engineers review code — comment on a line, approve, merge. Example: docs/examples/coach-review.md.
Reproducibility. The same trainctl.yaml and the same engine version
produce the same plan — in five years too. Nothing drifts under you and no
backend can shut down; pin the version in your training repo and every session
stays explainable: a rule ID in the plan, a commit in the history.
Agent (MCP)
The same engine as tools for an agent, so the interface becomes conversation: "what am I running today?", "release on Thursday — move the intervals", "how did last week go?"
Claude Code — as a plugin. The plugin brings the MCP tools, five coach skills
(/trainctl:review, /trainctl:debrief, /trainctl:shorten, /trainctl:what-if
and the coach persona) and two hooks: the coach instructions at session start in
a training directory, and trainctl check after an edit of plan/plan.yaml.
/plugin marketplace add dithiothreitol/trainctl
/plugin install trainctl@trainctl
trainctl init --agent claude writes .claude/settings.json into the training
directory, so the plugin is enabled there for anyone who clones it.
Codex reads AGENTS.md on its own. trainctl init --agent codex adds the MCP
server in .codex/config.toml (loaded once you trust the project); or install
the plugin with codex plugin marketplace add dithiothreitol/trainctl and
/plugins. Use one of the two, not both. Details and limits:
docs/integrations/agents.md.
Without the plugin — Claude Code:
claude mcp add trainctl --env TRAINCTL_DIR="/path/to/my-training" \
-- npx -y trainctl-mcp
Any MCP client works — the generic form:
{
"mcpServers": {
"trainctl": {
"command": "npx",
"args": ["-y", "trainctl-mcp"],
"env": { "TRAINCTL_DIR": "/path/to/my-training" }
}
}
}
The tools run over the same handlers the CLI uses, so the agent and your
terminal can never disagree: trainctl_plan, trainctl_today, trainctl_week,
trainctl_season, trainctl_log, trainctl_shift, trainctl_why, trainctl_diff,
trainctl_check, trainctl_init, trainctl_push, trainctl_pull,
trainctl_adapt, trainctl_replace, trainctl_migrate, trainctl_shorten, trainctl_desk, trainctl_reschedule,
trainctl_export, trainctl_review, trainctl_status, trainctl_rule. The
server also exposes plan/PLAN.md, trainctl.yaml, AGENTS.md and every rule as
resources (trainctl://plan, trainctl://rules/I-7, …), and the weekly review
and the post-run debrief as prompts.
The local Codex plugin also exposes trainctl_workspace to select an absolute
training directory before using these tools. See plugin setup.
The AGENTS.md written by trainctl init turns the agent into a coach rather
than a command runner: ask before regenerating a plan, ask for context when a
week was missed, correlate what it can see (calendar, tracker, on-call) with the
training week — and never invent numbers.
trainctl MCP questions
Does trainctl require an account or a database?
No, it requires no account, no database, and no backend. Everything is stored as files in your current directory.
How does the AI agent use trainctl?
The MCP server allows an AI agent like Claude Code or Codex to access your training plan and act as a coach through the tool.
What are the system requirements for installation?
The only requirement is Node.js version 22.18 or higher.
Can I use my own race results to set training zones?
Yes, zones are derived from your race results rather than watch estimates.