Skip to main content

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

  1. Ingest .fit files from a target directory or the standing inbox — dropped there by hand, or fetched by a configured connector's fitdocs pull (fitdocs itself never watches for them).
  2. 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.
  3. Compute training load through a pluggable LoadCalculator interface. 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.
  4. Show training history. fitdocs history renders 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 .fit file read. fitdocs recovery puts wellness signals against their own per-source baselines beside the load history; see Recovery.
  5. Render training blocks. fitdocs plan renders 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 of fitdocs sync and fitdocs 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) and fitdocs pull (fetching activities from it) — 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.

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 two connectors: folder, which needs no service at all, and intervals, which pulls the original .fit files of an intervals.icu account with a personal API key; both 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 and workout regions, and its effort-tag frontmatter keys (effort, effort_distance_m, effort_time_s, effort_event) — 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

Metadata

Release files for fitdocs 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fitdocs 0.2.0
File Size Uploaded Provenance Actions
fitdocs-0.2.0.tar.gz 860.3 kB With provenance Details for fitdocs-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fitdocs 0.2.0
File Interpreter ABI Platform Actions
fitdocs-0.2.0-py3-none-any.whl Python 3 none any Details for fitdocs-0.2.0-py3-none-any.whl

Total release size: 1.9 MB

Release files / fitdocs-0.2.0.tar.gz

Download URL fitdocs-0.2.0.tar.gz
Size 860.3 kB
Tags Source
SHA-256 checksum
How to use checksums
e44e964541f1bef742219ba0e9aa25f5d0d9732f50622d2f71fa518d9589fe24
BLAKE2b-256 checksum
How to use checksums
029e3a4bdda26572290c9666fd7f1252454ca7d4cadea433fa68fb4ab12b4361
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Oct 19, 2026.

Transparency log

Release files / fitdocs-0.2.0-py3-none-any.whl

Download URL fitdocs-0.2.0-py3-none-any.whl
Size 1.0 MB
Tags Python 3
SHA-256 checksum
How to use checksums
d2ab99416f86011220d93537a9910846f83d3ba91ad4f7cdea1f14e96c9388a3
BLAKE2b-256 checksum
How to use checksums
0a9ed198a35a2dd336e354c8e1562859c4508c1d6a30478736704b99219d0beb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Oct 19, 2026.

Transparency log

Security for fitdocs 0.2.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.

Select from 2 files

Attestation for fitdocs-0.2.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 Oct 19, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page