yootri
A triathlon training planner that fits a season to the hours you actually have,
and keeps it in your own browser. It is free, open source, and has no server of
its own — no account is required, and nothing is uploaded unless you ask it to be.
Live at https://yootri.gzarruk.com
What it does
- Fits a season to a race date. Give it a race and a rough annual hour
budget and it lays out periodised blocks — base, build, peak, taper — landing
on the day you race.
- Turns hours into actual sessions. A deterministic engine decides session
lengths, disciplines and zones from the week's budget. It never invents time:
if the week does not fit, it says so rather than quietly padding.
- Works around your life. Availability per day, standing constraints ("the
pool is shut on Mondays", "no more than three swims a week") and per-block
discipline splits all feed the fit.
- Drag-and-drop rescheduling, add/edit/delete sessions, mark sessions done.
- Logs what actually happened — duration, RPE, a note — separately from what
was planned, and reports compliance against the plan.
- Training paces from a result you ran. Enter a race or time trial — or drop
in the activity CSV Garmin Connect exports, or a single TCX or GPX — and every
Run session shows the pace band it is asking for, in min/km and min/mile.
Nothing is measured: the numbers are arithmetic on the time you gave it, and
replacing the result updates the whole season at once.
- Charts the season's training load, weekly or cumulative, per discipline.
Hand-drawn SVG; no charting library.
- Multiple named plans: create, switch, rename, duplicate, delete, export,
import.
Nothing is edited in place. Any change — yours or the coach's — is built as a
draft, checked, shown to you as a diff, and only written when you apply it.
The AI coach
The coach is optional and stays off until you configure it. It can read your
plan and propose changes; it cannot write to one. Everything it does lands in
the same draft-and-review gate as everything else, so the worst it can produce
is a proposal you reject.
- Bring your own API key. yootri has no server and no API account of its own.
- Your key stays in your browser. It is held in
localStorage, is never
written into a plan, and is never exported or synced. Anything that can run
script on the page could read it, so use a key you are willing to rotate.
- You pay your provider directly. Conversations are billed to your own
account. The model list is ordered cheapest first, and the default is the
cheapest model that can reliably drive the tool loop.
- I never see your data or your key. Requests go from your browser straight
to the provider you picked.
- Coach conversations never leave your browser. They are not synced and are
not included in an exported plan.
Two providers are supported: Anthropic, and anything speaking the OpenAI
Chat Completions shape — OpenAI itself, OpenRouter, Groq, Together, LM Studio
or Ollama — through an editable base URL. A local endpoint works well here and
keeps everything on your own machine.
Responses are generated by an AI model, not a human coach, and can be wrong.
Your data
- Local first. Everything saves to the browser's
localStorage and works
fully offline and signed out. This is a normal way to run yootri, not a
degraded one.
- Optional cloud sync. Sign in with Google to sync plans across devices via
Cloud Firestore. Last-write-wins by
updatedAt. Plans are readable only by
the account that wrote them — see firestore.rules.
- Never synced: your API key, your coach conversations, heart rate, and
sleep and overnight heart rate.
- Heart rate stays on this device. An imported activity file is parsed in
this browser and its heart-rate columns are stepped over; the only thing kept
is the one result you pick, and only its distance, time and date. Activities
synced from Garmin (below) bring each activity's average and maximum heart
rate to this browser, which keeps them in its own storage: they are never
written into a plan, so never synced and never exported. The same goes for
any heart-rate thresholds you enter for training load. If you use the coach,
the training load it reads — partly worked out from heart rate — goes to your
AI provider with the rest of what it reads.
- Garmin, for your own account. Garmin has no route a static page can use,
so
tools/garmin-bridge is a small program
you run on your own computer (make garmin-login, then make garmin). The
page asks it for recent activities on 127.0.0.1, matches them to your planned
sessions, and logs the ones you confirm. It is off unless you pair a browser
with it, and it uses an unofficial library, so a change on Garmin's side can
break it.
- Sleep and overnight heart rate, off by default. With the bridge started as
YOOTRI_GARMIN_OVERNIGHT=1 make garmin and the box ticked in the Garmin
panel, a sync also reads minutes asleep, the overnight HRV average and resting
heart rate, night by night — none of Garmin's own scores. They stay in this
browser like heart rate: never on a plan, never synced or exported, never
given to the coach. The weekly review sets your last seven nights beside the
four weeks before them and, when they are outside your usual range, says so
beside the option to make one session of next week easy. See
the bridge README.
- Bike workouts to Garmin, off by default. With the bridge started as
, puts your upcoming bike
sessions in your Garmin calendar as structured workouts (warm-up, intervals
at a power target, cool-down) and does one session. A
trainer app linked to your Garmin account can then pick them up. This rests
on Garmin endpoints nobody promised to keep: see
for the risk and for what to do when Garmin changes its sign-in.
Plan file format
Plan menu → Export this plan writes the file, and Import plan… reads it
back. That file is the only thing import accepts — there is no separate template
format. If you just want to see one,
assets/example-plan.json is a real 20-week 70.3
season, and the import panel will load it for you.
An export wraps the whole plan record in a small envelope:
{
"_type": "im703-plan",
"version": 1,
"exportedFrom": "yootri.gzarruk.com",
"plan": { "...": "the fields below" }
}
A bare plan object — the contents of plan, without the envelope — is accepted
too.
| Field | What it is |
|---|
schema | 3. Older files are upgraded on the way in; the file on disk is not touched. |
id, name | Identity. An import always mints a fresh id, so importing your own export sits next to the original rather than replacing it. |
start | "YYYY-MM-DD", the Monday week 0 begins on. Required. |
profile | Race date and type, per-day availability in minutes (the season's biggest week), constraints, and any per-block discipline splits. |
season | One entry per week: absWeek, block, recovery, load, hours. This is the target curve the chart plots against. |
weeks | The sessions themselves, keyed w0…w{n-1} to match season. |
done | Completion flags, keyed by session id. |
actuals | What actually happened, keyed by session id. |
weekBudgets | Per-week hour budgets you have pinned, keyed w0… |
chartmode, charthidden, view | Display state. |
Two things do not travel in a file. Your coach conversation is local to the
browser it happened in and is never written out. Your API key is not part of
a plan at all, so it is never exported or synced.
A plan is self-contained on purpose: the season only means anything against the
budget and the runway it was fitted to, so both come across with the sessions.
Import is the exact inverse of export — if a field survives the round trip it is
in the table above, and
tests/portable.test.js is what holds that true.
Run it locally
Assets use relative paths and ES modules need a real origin, so serve the folder
rather than opening index.html from disk:
make dev # http://localhost:8000/, opens a browser
make dev PORT=8001 # when 8000 is taken
make dev OPEN=0 # do not open a browser
make stop # free port 8000 again
make stop is there because a dev server outlives the terminal it was started
from — close the window instead of pressing Ctrl-C and it keeps the port, with
its parent shell gone. make dev says so when it hits that, and names the way
out rather than leaving you to remember the lsof incantation.
That runs tools/dev-server.mjs: one small Node script,
no dependencies. Any static server works — python3 -m http.server 8000 is fine — but this one is deliberately stricter than the folder deserves,
because each thing it refuses to do costs an afternoon otherwise:
- it serves
.js as JavaScript, without which the browser silently refuses
every engine module and the page loads with nothing behind it,
- it sends
Cache-Control: no-store, so a saved edit is never a stale page,
- it 404s a missing file rather than falling back to
index.html,
- and it 404s
Season.js when the file is season.js. That one only matters on
macOS, where a case-wrong path opens happily and then 404s on Pages, which
runs on Linux.
Open it as localhost, not 127.0.0.1. Google sign-in works on the first
and fails on the second: localhost is on Firebase's authorized-domain list by
default and the bare IP is not. Nothing else in the app can tell the difference,
which is what makes it a confusing ten minutes. make dev prints and opens the
spelling that works.
There is no build step and there are no dependencies. package.json exists only
so node --test can run the engine's unit tests:
make test # npm test
make check # the whole CI gate: unit tests + repo hygiene
Every pull request runs the same npm test on Node 20, 22 and 24, plus a check
that nothing private, credential-shaped or broken-linked has been committed —
this repo is a website, so anything merged here is published. See
.github/workflows/ci.yml.
Forking and self-hosting
The app is static — any web server or static host will do, and GitHub Pages
serves it straight from the repo root.
To be aware: cloud sync will not work on your own domain until
you point it at your own Firebase project and add your domain to that project's
authorized list. Until then the app runs local-only and says so in the UI, with
an explanation of what still works. That is a supported way to use it — if you
do not want sync, leave it exactly like that and everything except cross-device
syncing and Google sign-in works normally.
To set sync up, see FIREBASE_SETUP.md.
To deploy on GitHub Pages: Settings → Pages → Source = Deploy from a
branch, Branch = main, Folder = / (root). To serve from your own
subdomain, replace the CNAME file with your domain, add a CNAME record at
your DNS host pointing to <your-user>.github.io, and tick Enforce HTTPS
once DNS has propagated.
Layout
| Path | What it is |
|---|
index.html | Markup, styles, DOM, storage and cloud sync |
assets/coach/*.js | The engine: pure ES modules, no DOM and no I/O |
assets/nocturne.css | The "Nocturne" design-system base |
tests/ | npm test, plain node --test, no framework |
tools/ | The dev server, and an optional Strava relay that is off by default |
firestore.rules | Firestore security rules (owner-only, default deny) |
.github/workflows/ | CI: unit tests on three Node versions, repo hygiene, CodeQL |
CLAUDE.md is the contributor and architecture document. Read it
before changing the engine.
Disclaimer
yootri is a training planner. It is not medical advice, and the developer is
not a certified coach, personal trainer, or medical professional. Consult a
physician before beginning any training programme. Endurance training carries
inherent and significant risks of injury, illness and death, and you are solely
responsible for your own training decisions.
The full text is in the app, under About & disclaimer in the footer.
Support the project
yootri is free and MIT-licensed, and always will be. There is no paid tier, no
licence key, and nothing to unlock.
If it is useful to you and you would like to support its development, there is a
supporter page on Gumroad. That is a
contribution to the work, not a purchase of the software.
License
MIT — see LICENSE.
SPDX-License-Identifier: MIT
