Describe your training in a chat. Your AI agent organizes the details.
Keep a portable history that your next agent — or your coach — can understand.
Use this template · Explore the demo · Русский · Agent protocol
“Ran 5 km in 28 minutes. Then pull-ups: 8, 7, 6. Last set was tough.”
Your agent records a running block and three strength sets, keeps the note, validates the entry, and refreshes your report. Missing details stay unknown — it doesn't invent your heart rate or weight.
“Actually, the second set was nine.”
It updates the existing set with a correction, without creating another workout.
Workout.md is a repository template and an agent protocol, with a small offline reporting tool. Bring a file-capable AI agent and your own private copy. There is no embedded chatbot, subscription, or AI API key required by this project. Your agent service may have its own costs and data policies.
| For you | For your agent | For your coach |
|---|---|---|
| Write naturally, in your language | Clear entry point in AGENTS.md |
A readable offline HTML report |
| Run, ride, swim, lift, or mix activities | Stable IDs, explicit units, validated records | Dated results and training notes |
| Own ordinary files and Git history | Current context without old chat history | Approved plans and open proposals |
| Change agents without starting over | No invented facts or silent plan changes | Share the report or grant repository access |
Available now: multisport sessions, individual sets, intervals, corrections, profile, plans, proposals, validation, progress charts and a current-state summary.
Planned: Garmin and Apple Health import with duplicate reconciliation. These connectors are not included in this release.
Click Use this template, name your journal and choose Private. Clone your new repository and open it in your agent. Prefer a template copy over a public fork for real training data.
The personal journal starts empty. All sample workouts live separately in examples/demo/ and are fictional.
Paste this into a file-capable agent:
Read AGENTS.md and follow its linked journal protocol. Set up this journal for me. Ask only for the essential missing preferences, including my timezone and weight convention. Install the local Python tooling in a virtual environment, validate the empty journal, and build my first report. Do not use the demo as my history. Do not publish my data.
The agent can do the setup for you. To do it yourself, use Python 3.10+:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m workoutmd validate
python -m workoutmd buildOn Windows, create the environment with py -m venv .venv and activate it with .venv\Scripts\Activate.ps1 in PowerShell. On later visits, activate the environment again before running commands.
“Log today's ride: 24 km, 68 minutes moving, 75 minutes total. Easy pace, windy.”
Continue with fragments, add another activity, or correct an earlier entry. The agent manages YAML; you don't have to. Open reports/index.html in your browser to see your journal. It works offline; CURRENT.md provides a quick text overview.
Voice works when your chat application supports speech-to-text. Workout.md itself doesn't record or transcribe audio.
Or generate it locally:
python -m workoutmd validate --root examples/demo
python -m workoutmd build --root examples/demoOpen examples/demo/reports/index.html. This does not add examples to your own journal.
| Agent setup | Entry point |
|---|---|
| Codex | AGENTS.md |
| Claude Code | CLAUDE.md, which imports AGENTS.md |
| Other agents with repository access | Ask them to read AGENTS.md and its linked documents |
| Read-only chat | Can propose entries; you must save and validate them separately |
Compatibility means readable files and documented instructions, not a claim that every model or agent client has been tested. Logging quality depends on your agent. The validator catches structural errors; you and your agent still check whether a record matches what you said.
AGENTS.md How an agent should work
CLAUDE.md Claude entry point
CURRENT.md Generated state for quick handoff
athlete/profile.yaml Preferences and active plan
sessions/YYYY/MM/ Canonical workout records
plans/ Versioned training plans
proposals/ Suggestions and human decisions
catalog/ Exercise names and aliases
reviews/ Human or agent narrative reviews
reports/index.html Generated offline report (Git-ignored)
templates/ Starting points for new records
schemas/ Documented, machine-checked formats
examples/demo/ Fictional data, isolated from your journal
YAML owns the facts. Reports are derived. Plans are not completed workouts. Agents may suggest changes; people approve them. See the data format, journal rules and tag vocabulary.
Keep real data in a private repository. The CLI makes no network requests and the generated report needs no external scripts, fonts or telemetry. Your chosen agent provider has its own privacy policy.
A report can include your notes and training details: inspect it before sharing. Repository access may also reveal Git history. !notes/ is reserved for private internal notes and excluded from Git/report input; .gitignore does not erase already committed data.
The public demo contains only fictional records. No workflow deploys your personal journal. Learn more in Security and privacy.
Try it with your agent, report a confusing step, add a fictional edge case, or improve an adapter design. Read CONTRIBUTING.md. New features use Spec Kit specifications; everyday logging does not require Spec Kit.
Roadmap · Changelog · MIT license
Workout.md is an independent project, not affiliated with agent or wearable vendors. The banner was generated for this project; all demonstration data is synthetic.
If this project was useful to you, feel free to support further development:
