ledger
CLAUDE.md0 starsChanged 12 days agoMITView on GitHub
Web app that reads the runner's own Garmin Connect data through Garmin's Personal API (activities, profile for now). React 19, styled-components, zustand, Vite 8, Vitest, Playwright, pure JS. The app's name is Ledger (masthead, tab title, footer). Never brand it "Garmin": it reads Garmin Connect data but isn't Garmin's, and the footer says so. - The Personal API key is GARMIN_PERSONAL_API_KEY in .env at the repo's root (gitignored), read by vite.config.js with loadEnv(…, "GARMIN_"). Never give it a VITE_ prefix:…
- Reads credentials
In this repository6 other files it gives its agents.
- aerobic-progressSkill
- load-checkSkill
- race-predictorSkill
- refresh-reportsSkill
- trail-predictorSkill
- weekly-reviewSkill
The file
We split this CLAUDE.md into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 23
No static deploy: without the middleware the page has no API.
- Very specific: line 66
Every activity is trimmed to KEPT in src/store/cache.js: reading a new field means adding it there and bumping CACHE_VERSION.
- Distinctive: line 68
Only the theme, the view, the picked activity types and the measure go through zustand's persist (localStorage).
- Very specific: line 145
Never commit an account's data.
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Ledger: project rules
Web app that reads the runner's own Garmin Connect data through Garmin's Personal API (activities, profile for now). React 19, styled-components, zustand, Vite 8, Vitest, Playwright, pure JS.
The app's name is Ledger (masthead, tab title, footer). Never brand it "Garmin": it reads Garmin Connect data but isn't Garmin's, and the footer says so.
The key stays on the server
- The Personal API key is
GARMIN_PERSONAL_API_KEYin.envat the repo's root (gitignored), read byvite.config.jswithloadEnv(…, "GARMIN_"). Never give it aVITE_prefix: Vite inlines those into the bundle. server/garmin.jsis the only code in the page's path that sees the key or a token: middleware on Vite's dev and preview servers that answers/api/garmin/*. It exchanges the key for a JWT (Authorization: ApiKey …), keeps it in memory until an hour before itsexp, and forwards GETs withAuthorization: Bearer …. One forced re-exchange on a 401. Nothing but GET.- The page (
src/api/garmin.js) calls same-origin/api/garmin/<Garmin path>and never holds a credential. Paths come from Garmin's client (github.com/garmin/connect-personal-api-python,client.py): copy new ones from there. - No static deploy: without the middleware the page has no API. Hosting it means a server
function doing what
server/garmin.jsdoes, plus access control: anyone who reaches the proxy reads the account. Same forvite --hoston a shared network.
Reading activities
- The store (
src/store/store.js) is a factory taking the client and the cache: tests pass fakes. A newerconnectdrops an older one's answer (generation). - Garmin answers 500 past a
limitof 100: never ask for larger pages. - Probed 2026-10-26: a
startpast the end answers[](200), so parallel pages are safe; anendDatea year or more ahead answers[]for the whole range, so the incremental read sendsstartDatealone. - Probed 2026-10-28: list items carry training effect (
aerobicTrainingEffect,trainingEffectLabel…), power, cadence anddifferenceBodyBatteryfrom mid-2023 on, nevervO2MaxValue. HRV (/hrv-service/hrv/daily/{start}/{end}) answers up to a year per request (400 days → 400), 204 for a range with no readings; this account's start in 2024-01. Daily summaries (heartRate.restingValue) answer up to 365 days, sleep summaries up to 31 (an object keyed "0", "1"…); both start 2024-01 here, older daily summaries carry no heart rate. Heart-rate zones are the current settings only. Activity detail carries no RPE/feel. Runs carryfastestSplit_5000/10000/21098/42195(best stretch inside the run) from 2024 on; the Personal API has no race-prediction endpoint, sosrc/utils/race.jsscores them (VDOT).eventType.typeKeyis "race" on one activity in 1074: trail events (src/utils/trail.js) are also a plan's past races or any day of 100 effort-km or more. Their time iselapsedDuration(the race clock):durationstops while the watch is paused (2h20 short on one 30 h race here). A plan race line with a result (…, 15:26:19or…, DNF) wins over the watch: the official course and clock, at any age; a DNF day is never an event. A line may name its ground (runnable,technical): one factor each on the time on the move, against untagged courses. Without a curve (under 3 events, or within twice each other's length), times scale from one event with an assumed exponent (assumed), never passed off as fitted.recentForm(the last 24 months' events against the curve) sits beside each time asformTime, never folded into the fit. The watch is no result sheet: a DNF recorded to the drop reads as a slow finish. A finished race run badly (in a group, in bad weather) stays in the fit: dropping bad days makes the band optimistic. - Probed 2026-10-29: each event's
prepRunKm(running km of the 84 days before, null where the history starts inside them: a gap, never a rest) lined up withoffPcton 7 ultras (190 effort-km or more) and not on all 10 events with history. Shown, never fitted, until 8–10 ultras carry it.fit.outOfSamplerefits without each event and predicts it: the band's real cover (±16%, 9 of 16 inside ±13% here), whichspreadPct, measured on the fitted events, flatters. Training load before an event (ratio, chronic) explained nothing on the 5 that have it, andchronicreads 0, not null, before load data exists (mid-2023). The trail-predictor skill quotes readiness (load ratio, efficiency, HRV, resting HR) only for a race 21 days away or less, beside the time, never as an adjustment. - The cached history (IndexedDB, one entry per account) is merged by
activityId; only Refresh sees an activity edited or deleted on an older day. - Every activity is trimmed to
KEPTinsrc/store/cache.js: reading a new field means adding it there and bumpingCACHE_VERSION. - Only the theme, the view, the picked activity types and the measure go through zustand's persist (localStorage). The history never does.
Pages
- The type filter and the measure drive every chart and total below them; Training alone ignores the filter. Filter as the pages render, never at fetch time: changing it costs no request.
- Sums are pure functions in
src/utils/(yearStats.js,metrics.js,training.js), never in components. - The Year page compares with another year (
againstin the store, the year before when none is picked; kept as the shown year changes, not persisted): the tiles' changes and the running total's dashed line follow it, both cut at today's date when either year is the current one. - Training is one year only (the whole history on one axis was unreadable), read with the year before so January's 28-day load is whole. It screens first and says what it set aside: a number never silently drops data.
startTimeLocalis the watch's clock with no zone: read it as a string, never throughDate.- Design system: tokens come from
@totorototo/trail-tokens;src/theme/Theme.jsonly re-exports it. Never edit token values here. Shared control styles are fragments insrc/theme/controls.js. Component styles go in*.style.jsnext to the component. - Spacing is the design system's 4px grid:
var(--space-4), never a rem or px literal.
Insights
npm run export(scripts/export.mjs) reads the history from Node with the same key, token source and pages of 100 (server/export.js), trims it withtrim, and writesdata/activities.jsonanddata/metrics.json(insightsinsrc/utils/insights.js).data/is gitignored: it is the account's data.- Wellness goes into
data/wellness.json: HRV (readHrv) and resting HR (readRestingHr) a year per request back from today, stopping at the first year with no reading; sleep (readSleep) a month per request from the first of those, without stopping (a month off the watch happens); the running zones as set now. The skills read HRV against Garmin's balanced band, never a baseline of ours; resting HR has no Garmin band, so its baseline is the median of the 28 days before (restingSummary). data/plan.mdis the runner's own races, planned blocks and health notes (templatescripts/plan.example.md), parsed byparsePlan(src/utils/plan.js): a line it can't read is listed inplan.ignored, never dropped silently.metrics.jsonis built only from the pages' own sums (metrics.js,training.js,yearStats.js), so a skill's numbers match the app's. Changing a field's meaning or removing one means bumpingMETRICS_VERSIONand the version the skills check.- The skills (
.claude/skills/*/SKILL.md) quote numbers frommetrics.jsonand interpret them; they never compute one. A number a skill needs and doesn't find goes intoinsights, with a test.
Reports
- Each skill ends by publishing its reading as a page: it writes only words to
data/reports/<skill>.notes.json, andnpm run report -- <skill>(scripts/report.mjs, pure picking inscripts/reports/build.js) takes the numbers frommetrics.jsonitself and fillsscripts/reports/<skill>.html. A note the builder can't read fails the build by name. - Two pages have no skill or notes:
race-formandtraining-breaks(src/utils/breaks.js).npm run report -- <page>fills them frommetrics.json, and pure functions inbuild.jsturn the numbers into their words, so the words can't go stale beside them. Probed 2026-11-05: the longest running break of the 84 days before a long race separates only 2 of 4 DNFs (at most 14 days before a finish; 20 and 37, against 8 and 5); the page says so. /refresh-reports(.claude/skills/refresh-reports/) exports, reruns every report and republishes each page to its link. It's meant for a Monday scheduled task in Claude Desktop, set up in the app rather than in this repo.- The pages are Ledger in Trail Suite's voice (
scripts/reports/base.css): mono titles, numbers and labels, ledger rows on 10% hairlines, violet for trends, the theme's own grounds (light #c4c4c4). No cards, pills or gradients. data/reports/(gitignored) holds the pages andlinks.json, each page's claude.ai link: a run updates its page in place. Publishing uploads the account's data to claude.ai, private until the runner shares it.
Tests
- Unit tests never reach Garmin: the client and the middleware both take a
fetch, the store a fake client andmemoryCache().server/*.test.jsrun in Vitest's node environment. - e2e (
npm run e2e) runs the built app in Chromium with/api/garminrouted by the test (e2e/helpers.js), so it needs no key.
Data
- Never commit an account's data.
.gitignoreblocks.env,*.fit,*.zip,*.gpx. - Fixtures (
src/test/fixtures.js,e2e/helpers.js) are synthetic, in the API's shape.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

