Repository navigation
v0.4.0 — plugin for Claude Code and Codex, activity files, and a plan that keeps your decisions
Install: npx trainctl@0.4.0, MCP: npx -y trainctl-mcp@0.4.0, plugin for Claude Code and Codex from this repository (see docs/integrations/agents.md). New package: trainctl-sync-files. Full history in CHANGELOG.md.
Fixed — found by running every command on a fresh directory
reviewon a Sunday no longer reports the whole week's volume next to the
number of remaining sessions ("52 km across 1 sessions"); it shows what is
left of the week's target.- A directory without
trainctl.yamlnow points totrainctl initinstead of
trainctl plan, which would only have pointed back toinit. whyno longer prints "About 0 minutes" for a rest day, no longer states the
session's purpose twice, and lists each rule once with its text and
provenance instead of in two separate sections.loganswers with what the plan had for that day next to what was recorded,
says when an entry falls on a rest day, and returns structureddatafor MCP.- Messages print
plan/plan.yamlon every system (Windows printedplan\plan.yaml). - A plan generated by another minor version of the engine is reported in
today,week,why,reviewandcheck(informational; never fails
--strict). A plan file with a newer schema is refused with advice to
upgrade trainctl. - Rule sources link to
docs/science/FOUNDATIONS.mdon GitHub, pinned to the
release tag — the file is not part of the npm package, so the relative path
inwhy,deskandAGENTS.mdled nowhere after installation.
Changed — trainctl plan keeps what you decided (ADR-033)
- On an existing plan,
planregenerates only the future. Past and logged
days, pinned days, hand edits, approved shortenings and days whose new session
would exceed a saved time budget stay as they are. An approved volume baseline
fromadapt --applyis kept until you changeathlete.recentWeeklyKm.
Previously every regeneration silently discarded all of that — including on
the documented path "add a race result →trainctl plan". - The same training cycle keeps its phase boundaries; a different goal distance,
or a new goal after the race, starts a new cycle and keeps the earlier weeks
as history ("week 2/12" counts the current cycle). On race day the race
counts as done only when most of its distance is logged or synced (a day
logged as skipped never counts), so a morning shakeout before a postponed
race keeps the same cycle. - Right after
adapt --apply,planreproduces the approved days, including
strength sessions, time-budget caps and the day of the decision. Later,
strength follows the current phases andstrength.days. - A
plan/plan.yamlthat cannot be read (a merge conflict, a missing goal) is
never overwritten silently:planrefuses until it is fixed or--freshis
given, andstatusno longer suggests aplanthat would fail. trainctl diffshows exactly the regenerationplanwould perform.
plan --fresh(MCPfresh) starts over and lists what it discards.- Fixed: a race result recorded inside the plan's horizon did not reset the
calibration rhythm (W-12), so a regeneration could schedule a time trial a
week after a fresh 10 km result.
Added — a CLI you can script
--jsonon every command prints{ code, data, output }— the same data the
MCP tools return (ADR-035).-C <dir>/TRAINCTL_DIRfor the CLI, as the MCP server already had.TRAINCTL_TODAY=YYYY-MM-DDsimulates the date; every CLI and MCP output
announces it, and past-day protection and proposal expiry follow it (ADR-034).- Relative dates in the CLI:
today,tomorrow,yesterday,+N/-N,
weekday names in English and Polish. MCP tools stay ISO-only. trainctl logwithout flags in a terminal asks: pick a session from the last
week, then status, distance, time, RPE and a note.trainctl status/trainctl_status: profile validity, engine version,
calibration, key source (never its value),.envprotection, last pull,
journal, saved proposals with their validity today, uncommitted files.--commit [message]oninit,plan,log,shift,reschedule --apply,
adapt --applyandshorten --apply(MCPcommit) commits exactly the files
the command changed — never secrets,sync.jsonor other staged changes
(ADR-040).init --commitincludes.gitignorewhen it created it or when it
had no uncommitted changes before the secret patterns were added.todayshows the estimated duration and the next session.trainctl completion bash|zsh|fish|pwsh, examples undertrainctl help <command>.- Usage errors (unknown command or flag, a date that is not a date) exit with 2.
Added — trainctl in Claude Code and Codex (ADR-036)
- A plugin in
plugin/, with this repository as its marketplace for both agents:
/plugin marketplace add dithiothreitol/trainctl+/plugin install trainctl@trainctl
in Claude Code,codex plugin marketplace add dithiothreitol/trainctlin Codex.
It bundles the MCP server, the coach persona and four task skills
(review,debrief,shorten,what-if), and in Claude Code two hooks: the
coach instructions at session start in a training directory, and
trainctl checkafter an edit ofplan/plan.yaml. - Skills are generated from the same text as
AGENTS.md
(node tools/plugin/render-skills.ts);plugin.test.tsfails on drift. trainctl init --agent claude|codex|all(MCPagent) writes
.claude/settings.jsonor.codex/config.toml; existing files are never
overwritten.- MCP:
trainctl_ruleexplains a rule by ID with its source class and a link to
FOUNDATIONS for this version; resourcestrainctl://plan,trainctl://config,
trainctl://agents,trainctl://rules/{id}; promptsweekly-reviewand
debrief. CLI:trainctl rules [id]. trainctl checkreturns its findings asdata(--json, MCP, the hook).tools/release/bump-version.mjsmoves every pinned version together: packages,
plugin manifests, MCP configs, the hook and the CI examples.
Added — execution without a hub, a fuller calendar, context from the watch (ADR-037)
- New package
trainctl-sync-files: reads exported FIT, TCX and GPX files
(also.gz, as in Strava and Garmin bulk exports) as a pull-only source, with
no dependencies.trainctl pull --from <folder>(MCPfrom) and
sync.filesintrainctl.yamlforreviewwithout an API key. Skipped files
are named. The same run exported in two formats (start within 60 s, similar
distance) counts once, keeping the richest file: FIT, then TCX, then GPX.
initaddsactivities/to.gitignore. - The sync port is split into
ActivitySource(pull) andSyncProvider
(pull + push). pushsends races as race events (RACE_A/B/C) and strength sessions as
separateWeightTrainingentries, in their own requests: if intervals.icu
refuses either form, a race falls back to an ordinary entry, a warning says
so, and the running sessions are pushed regardless. Cleanup of stale entries
now covers everytrainctl-entry, not only workouts. Not yet verified on a
live intervals.icu account.reviewquotes resting heart rate, sleep and weight from the synced wellness
data, and RPE recorded in the hub where the journal has none — verbatim, with
the source, never averaged or turned into a verdict. HRV and CTL/ATL are
deliberately left out (H-1, P-4).
Added — the engine: time, life after the race, a plan without a race
- Time budget (
time.weeklyMinutes,weekdayMinutes,weekendMinutes,
E-2): weeks over the weekly budget get a lower volume target, days over their
limit are shortened with the same rules asshortenand carry the trade-off;
the plan says when the budget lowers the peak below the level recommended
for the distance, and what the peak would be without it (P-7/P-8). Races and
time trials are never cut.
A week keeps its macrocycle target; the volume the budget leaves is stored
next to it (timeCappedKm), andweek,adapt,diffandexportshow it.
A zone recalibration fromadaptchanges paces: day limits shorten
sessions that no longer fit from the current week, the weekly budget lowers
volume from the next week on, and volume goes up again throughplan. - Transition block after the goal race (R-8): after a half marathon or
longer, two weeks — about half the pre-race volume, easy only, first run on
the third day after a marathon (R-1), then back to normal with one accent;
one week at ~70% after a shorter goal (R-10). Strength returns in the second
week (R-9). Measured first:tools/corpus/post_race_profile.py(three long
races in the corpus — a weak basis, stated as such).todayandwhysay
"after the race" instead of "outside the plan", and a new goal set during the
block starts its cycle after it. - A plan without a race (
goal.kind: base,until, P-11): base weeks only,
deload every fourth week, growth to your documented peak and a plateau; no
taper, no prediction, no race pack. - Strength variants and journal: two weeks of getting into it (F-18), then
heavy sessions, one maintenance session a week in the peak (F-12, F-14);
trainctl log --strength done|skipped [--minutes](MCPstrength) records a
session without touching the run entry of the same day;reviewandtoday
show it. - Trail results no longer calibrate road zones while a road result exists
(Z-10); a trail-only calibration is used with a warning. - Rules E-2, F-18, P-11, R-8, R-9, R-10 and Z-10 in FOUNDATIONS §10, marked as
engineering choices where no source exists. The corpus backtest is unchanged
(volume 1.04, Δ accents 0, Δ sessions 0, tune-ups 6/6).
Docs
- README command tables list
shortenand the missing flags; tool lists no
longer carry a count that drifts.docs.test.tskeeps both READMEs and the
MCP README in step withbin.tsandserver.ts. - CI examples install the published package (
npx trainctl@<version>) instead
of cloning the engine and running Node 23. CLAUDE.mdfor coding agents working on this repository.