fitdocs
An installable personal knowledge manager for fitness. Consumes .fit files and
writes one markdown document per workout — rich, readable activity pages for
running, cycling, and weight training, with charts and computed training load.
Built to plug into a larger markdown PKM (wiki-style, Obsidian-compatible) as a first-class path, while remaining feature-complete standalone.
Install
fitdocs installs as a single console entry point with either standard isolated-application installer:
uv tool install fitdocs
pipx install fitdocs
See Install
for the full first-run path — installing from a checkout to run unreleased
changes, choosing a data root, getting .fit files where fitdocs finds
them, the first run, and what differs between a standalone data root and one
inside an existing markdown wiki.
What it does
- Ingest
.fitfiles from a target directory or the standing inbox — dropped there by hand, or fetched by a configured connector'sfitdocs pull(fitdocs itself never watches for them). - Render one markdown doc per activity — summary metrics, laps/splits or sets/reps, and embedded charts (e.g. the power-vs-heart-rate hero graph) — modeled on fitdocs.ai's activity views.
- Compute training load through a pluggable
LoadCalculatorinterface. fitdocs ships one built-in methodology,threshold, and is otherwise the carrier: any other calculator is a plugin, installed or dropped in locally, and contributions are welcome. If an activity is missing data a calculator needs (e.g. max heart rate, a threshold pace), fitdocs prompts for it and completes the calculation; when the activity predates the prompt, fitdocs also asks whether the answer covers earlier activities too. - Show training history.
fitdocs historyrenders one longitudinal page — a fitness/fatigue/form model and chart built from the training load already recorded on your workout documents — with no new data to enter and no.fitfile read.fitdocs recoveryputs wellness signals against their own per-source baselines beside the load history; see Recovery. - Render training blocks.
fitdocs planrenders one block page per source in your plan directory, with one planned-workout page per row underneath it — rebuilt from your plan sources and reconciled against your logged workout pages; the same pass also runs at the end offitdocs syncandfitdocs regen(see Training blocks).
Organizing workouts into cycles/training blocks was deliberately deferred
through the first releases; Phase 7 of the roadmap (2026-09-15) adds training
blocks — a plan document rendered from an athlete-owned source and reconciled
against logged workouts — as the training-blocks (shipped: the plan
source, the two page types and fitdocs plan) and plan-resolution
(shipped: the reconciling pass chained after fitdocs sync/fitdocs regen
and run standalone through fitdocs plan) specs; only build-training-block
is not yet shipped.
Route maps
Outdoor activities get a Map section drawn over real basemap tiles.
Fetching those tiles, and the connector commands — fitdocs connect
(authenticating once against a configured source, or registering with a
relay), fitdocs disconnect (revoking a relay token), fitdocs pull
(fetching activities from it) and fitdocs publish --yes (posting to a
publish target) — are the only times fitdocs touches the network. What leaves your machine
and when, the persistent opt-out, choosing a provider, attribution, and the tile cache all now live in
Configuration.
Each map file carries one basemap image: the tiles under the route,
composed and cropped to the area the map shows, at the tiles' own pixel
density (one pixel per output unit for 256-pixel tiles, two for 512-pixel
tiles), and stored as a WebP image at a fixed quality. The route, markers
and attribution are drawn above it as vector shapes. The tiles themselves are
still cached and reused across maps while rendering. If a tile a map needs
cannot be decoded, fitdocs omits that document's Map section and prints a
warning that names the document, the tile and the cause (for example
BasemapError: tile z/x/y cannot be decoded: …). The rest of the document is
written and the run still succeeds. If your installed Pillow cannot encode
WebP, every command that renders workout pages stops with an error before it
writes anything, and tells you to reinstall Pillow from an official wheel or
build it with libwebp. Which viewers display the image is listed under
Map images.
Plugins
fitdocs ships one built-in training-load methodology, threshold, and
discovers any other calculator as a plugin, from two channels: an installed
Python distribution advertising the fitdocs.load_calculators entry point
(pip install fitdocs-mycalc is the whole install), or a local plugin
file/directory named by [plugins].path in <data-root>/fitdocs.toml. Run
fitdocs plugins at any time to see every registered calculator (id, version,
origin, modalities) and any plugin load errors — a plugin failure is always a
warning, never a run failure.
Local plugin files are executed as ordinary code with your own user
privileges — fitdocs applies no sandboxing. Only point [plugins].path at
code you trust.
See docs/plugins.md
for the full guide — the worked packaged example, the local-file alternative,
the public API surface, the compatibility policy, diagnosis of every
rejection reason, and (linked from there) how to write the calculator itself.
Agent skills
fitdocs packages agent skills inside the wheel. Run fitdocs skill to list
the packaged skills and their installed directories, and
fitdocs skill <name> to print one skill's installed directory and a
recipe for putting it where your agent can use it.
Install a packaged skill by copying its directory into your agent's skills directory — the open SKILL.md standard fixes no location, so your agent's own documentation is where you find it.
Verify a packaged skill is active by asking the agent to list its
skills; the packaged skill appears under its frontmatter name.
Update a packaged skill once you have upgraded fitdocs: run
fitdocs skill <name> again and replace the old directory with the new
one; the copied SKILL.md's metadata.version says which fitdocs release
it came from.
Four packaged skills ship today: build-training-block walks an agent
through building a training block from the athlete's answers as a plan
source, rendering it with fitdocs plan, amending it, and settling
ambiguous matches; fitdocs-workouts pulls new .fit files from the
athlete's configured connectors, drains the inbox into workout documents,
and reads the pull and drain reports; fitdocs-analytics teaches safe SQL
queries against the read-only workout index; fitdocs-dashboards teaches
putting a query's answer on a wiki page as a chart. See
Wiki Integration
for where each skill lands, how to confirm it is active, how to update it,
and an end-to-end recipe for adopting fitdocs into an existing wiki.
Inbox
fitdocs defines a standing inbox: get .fit files there however you like,
and fitdocs sync, run with no arguments, drains it — performing no
watching and no scheduling of any kind. See
Inbox
for the full interface: every settings key and its default, drain semantics,
the safeguards, and the disposition policy's never-delete guarantee.
Connectors
fitdocs connect authenticates once against a configured connector instance,
and fitdocs pull fetches what's new from it straight into the inbox, where
the existing drain picks it up like any other file. fitdocs ships five
connectors: folder, which needs no service at all; intervals, which
pulls the original .fit files of an intervals.icu account with a personal
API key and also publishes posts to it; relay, for a fitdocs relay;
strava, which publishes to Strava through a relay; and garmin, which
pulls the original .fit files and daily wellness of a Garmin Connect account
with a personal API key. All run on the framework —
credential storage, per-instance ledgers, and the pull report — any future
connector builds on. See
Connectors
for the full interface: configuring an instance, the credentials directory,
what leaves your machine and how to switch it off, and the terms-first
policy.
Training blocks
fitdocs plan renders every plan source in your plan directory into a block
page under blocks/, plus one planned-workout page per row in a subdirectory
per block. The plan directory itself is user-owned and read-only to
fitdocs: fitdocs never creates, writes, renames, or deletes anything
there. It is configured in the [plans] table of
<data-root>/fitdocs.toml, the same settings file [tiles], [inbox], and
[plugins] share, which is itself read-only to fitdocs.
| Key | Meaning | Default |
|---|---|---|
path |
The plan-source location. An absolute path is used as given; a relative path resolves against the data root. Never created by fitdocs. Must lie outside the owned paths — configuring it inside blocks/ or another owned path is a configuration error. |
"plans" (i.e. <data-root>/plans/) |
fitdocs plan, and the same pass chained at the end of fitdocs sync and
fitdocs regen, also reconciles each row against the logged workout pages,
resolving it to one of five states — matched, overridden, skipped,
not logged, or upcoming — a matched row further labeled exact (one
candidate), absorbed (several candidates, all taken by that one row — a
split session), or ambiguous when two or more planned workouts on the
same day compete for the same candidates, in which case the proposed
pairing is never presented as settled. An [[override]] entry in a plan
source pins a row to named logged workouts, or marks it skipped, ahead of
that automatic matching. Standalone or chained, the resolution shown is
re-derived from whatever the logged workout pages currently record —
nothing about the match is stored, and nothing is written back into a
workout page or a plan source.
Benchmarks
fitdocs derive-benchmarks [--out PATH] [--dry-run] runs two stages,
writing dated benchmarks to athlete.toml alongside your hand-recorded
entries. The tagged-effort stage turns races, tests and hard efforts marked
with the effort frontmatter key into threshold pace, lactate-threshold
heart rate and functional threshold power. It reports why a tagged page
was declined or failed.
The heart-rate stage derives resting heart rate from a single wellness
source's 28-day median (at least 14 daily values), and maximum heart rate
from the median of the three highest session peaks in the last 365 days;
each peak is sustained over 30 seconds. Resting evidence must disagree
with the value in force by more than 3 bpm for 14 consecutive days;
maximum evidence must disagree by more than 2 bpm, with no waiting period.
A hand-recorded value stays in force until this write-time rule permits a
derived entry; it is never modified. The ordinary dated selection rule is
unchanged: evidence before a later hand entry can narrow its applies_from
back-reach. The run announces takeovers; fitdocs check lists one while
its derived entry is the latest of that kind. To keep your own value,
record a later hand entry; leave the derived entry to accept it.
Preview with --dry-run, then run without it to write. After a changed
timeline, run fitdocs load --recompute to apply it to already computed
load, including affected dates before a hand entry. Large archives can
take several minutes because workout files are parsed again. See
Derived heart-rate benchmarks
for the evidence, precedence, takeover and back-reach rules.
Ownership
fitdocs writes into a wiki it does not control, so what it owns and what you own is a published, versioned contract, not an implicit arrangement: see the fitdocs Ownership Contract.
In short: fitdocs owns workouts/, workouts/assets/, history/,
history/assets/, recovery/, recovery/assets/, blocks/, fit-archive/,
.cache/, and .fitdocs/
under your data root (plus any location your fitdocs.toml settings
configure it to write into — the Inbox's path and
processed_dir are the first example), and writes nowhere else. history/
and history/assets/ hold a second, generated document type — the
training-history page fitdocs history writes, alongside the per-workout
documents under workouts/ — and carry no user-owned content of their own.
blocks/ holds two further generated document types — one block page per
plan source and one planned-workout page per row, written by fitdocs plan
— of which the block page carries one user-owned region, notes, preserved
the same way a workout document's notes region is; the planned-workout
page carries no user-owned content. You own every workout document's
notes, workout and post regions, and its user-owned frontmatter keys
(the effort tags effort, effort_distance_m, effort_time_s,
effort_event, and publish); fitdocs owns the published region, which
fitdocs publish --yes fills with links to your posts — see the published
contract for the full detail. And athlete.toml's hand-added keys survive
every fitdocs write. Every generated document carries a provenance stamp,
and the five owned directories a human or agent browses — workouts/,
history/, blocks/, fit-archive/, and dashboards/ — each carry an AGENTS.md
restating the same contract for LLM agents maintaining the wiki.
Development workflow
All feature work follows Kiro-style Spec-Driven Development via
cc-sdd (/kiro-* skills in Claude Code).
Start with .kiro/steering/roadmap.md for the current plan; .kiro/specs/
holds every feature spec (requirements → design → tasks → implementation),
and docs/reference/ holds the research and methodology references backing
them.
Learn more
- Documentation index — the single entry point into every page below.
- Install — the full first-run path, standalone or wiki-hosted.
- Configuration — the data-root contract, the settings file, and the network/offline behavior.
- Inbox — the full inbox interface.
- Connectors — configuring instances, credentials, and
fitdocs connect/pull. - Compatibility policy — what a version number promises.
- Plugin platform — the calculator plugin API.
- Ownership contract — what fitdocs owns in your data root and what you own.
Metadata
Release files for fitdocs 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| fitdocs-0.3.0.tar.gz | 969.4 kB | With provenance | Details for fitdocs-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| fitdocs-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for fitdocs-0.3.0-py3-none-any.whl |
Total release size: 2.1 MB
Release files / fitdocs-0.3.0.tar.gz
| Download URL | fitdocs-0.3.0.tar.gz |
|---|---|
| Size | 969.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d9db35ee46b6ab54d814acd8efcce230c2bf020cadd5e67ec450dce60e6ec888
|
|
BLAKE2b-256 checksum How to use checksums |
216f4698a082083bf25b66fa35cf1a7480aa72c6d10da5a9b8a252c5abbd64b3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logRelease files / fitdocs-0.3.0-py3-none-any.whl
| Download URL | fitdocs-0.3.0-py3-none-any.whl |
|---|---|
| Size | 1.2 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ba16d23b7e3e3957de6b329084cdeb87d4fc5c6c10a192212df42aa26325b393
|
|
BLAKE2b-256 checksum How to use checksums |
4041a847deed3d4ff502a43a200da8293b7366b2366cbd3b259ab4c6dffc5ac8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logSecurity for fitdocs 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for fitdocs-0.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.