Fitness Agent

Fitness Agent is a local-first Strava to Obsidian workflow for athletes, coaches, and personal knowledge base users.

It authenticates with Strava, fetches recent activities plus fine-grained streams, renders structured Obsidian notes, writes directly into a local vault, and generates a ready-to-use dashboard with weekly and monthly review notes.

The repository also includes two post-sync skills:

• fitness-insights analyzes notes already stored in Obsidian and generates deeper trend views, load-proxy reports, and visualization notes.
• fitness-planner turns those historical notes into forward-looking next-week or next-two-week training plans.

Features

• Strava OAuth with automatic token refresh
• Activity list and activity detail fetch
• Strava streams support for route and intensity checkpoints
• Obsidian-friendly Markdown with structured frontmatter
• Direct local vault writes
• Auto-generated Fitness Dashboard.base
• Auto-generated weekly and monthly review notes
• Advanced post-sync analysis via fitness-insights
• Auto-generated Fitness Insights.base, snapshot, and trend notes
• Forward-looking planning via fitness-planner
• Auto-generated Training Plans.base and plan notes for the next 7 or 14 days
• Portable standalone skill package for Codex / SkillsMP
• Claude-compatible plugin package and marketplace manifest

What gets written to the vault

Running a sync creates or updates files like:

Fitness/Strava/
├── Activities/2026/03/2026-03-15-run-123456789.md
├── Dashboard/Fitness Dashboard.base
├── Dashboard/Fitness Dashboard.md
├── Insights/Fitness Insights.base
├── Insights/Fitness Snapshot.md
├── Insights/Training Trends.md
├── Plans/Training Plans.base
├── Plans/Fitness Planner.md
├── Plans/Generated/2026-03-16-next-7-days-auto.md
├── Reports/Weekly/2026-W11.md
└── Reports/Monthly/2026-03.md

The dashboard files use Obsidian Bases views over the generated activity notes, so one sync gives you both raw notes and analysis surfaces. Running fitness-insights adds deeper post-sync analysis, and fitness-planner adds an upcoming plan built from the same note history.

Requirements

• Python 3.9+
• A Strava API application
• A local Obsidian vault

Recommended Strava redirect URI:

http://localhost:33371/callback

Quick Start

1. Authenticate with Strava:

python3 fitness_agent.py auth login \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

1. Configure your vault:

python3 fitness_agent.py config set-vault \
  --vault-path "/path/to/YourVault" \
  --default-folder "Fitness/Strava"

1. Sync recent activities and generate the dashboard:

python3 fitness_agent.py sync latest --limit 5

1. Regenerate advanced insights from the notes already written into the vault:

python3 skills/fitness-insights/fitness_insights.py analyze refresh

1. Generate the next training plan from the existing notes:

python3 skills/fitness-planner/fitness_planner.py plan generate --days 7

Common Commands

List recent activities:

python3 fitness_agent.py activities list --limit 5

Export a single activity as Markdown:

python3 fitness_agent.py activities export --activity-id 123456789

Write a single activity into the vault:

python3 fitness_agent.py vault write --activity-id 123456789

Show CLI help:

python3 fitness_agent.py --help

Refresh the advanced analysis package:

python3 skills/fitness-insights/fitness_insights.py analyze refresh --weeks 16

Generate a future plan:

python3 skills/fitness-planner/fitness_planner.py plan generate --days 14 --goal auto

Repository Layout

.claude-plugin/marketplace.json   Marketplace manifest for Claude-compatible plugin installs
plugins/fitness-agent/            Claude-compatible plugin package
plugins/fitness-insights/         Claude-compatible plugin package for post-sync analysis
plugins/fitness-planner/          Claude-compatible plugin package for future plan generation
skills/fitness-agent/             Standalone Codex skill package
skills/fitness-insights/          Standalone Codex skill package for advanced analysis
skills/fitness-planner/           Standalone Codex skill package for plan generation
skills/fitness-agent/src/         Python implementation
skills/fitness-insights/src/      Python implementation
skills/fitness-planner/src/       Python implementation
tests/                            Unit tests
fitness_agent.py                  Root CLI entrypoint

Local Usage Guide

For a Chinese guide focused on local installation and local skill usage, see:

• docs/local_skill_usage.md

Packaging

This repository ships two installation shapes:

• skills/fitness-agent
• A self-contained standalone skill package suitable for Codex and for SkillsMP discovery from a public GitHub repository.
• skills/fitness-insights
• A self-contained standalone skill package that scans existing Obsidian activity notes and writes advanced analysis artifacts.
• skills/fitness-planner
• A self-contained standalone skill package that scans existing Obsidian activity notes and writes upcoming training plans.
• plugins/fitness-agent
• A Claude-compatible plugin source directory referenced by .claude-plugin/marketplace.json.
• plugins/fitness-insights
• A Claude-compatible plugin source directory for the post-sync analysis skill.
• plugins/fitness-planner
• A Claude-compatible plugin source directory for the plan-generation skill.

The standalone skill and the plugin package are both self-contained and do not rely on machine-specific absolute paths.

Configuration

Default config path:

~/.fitness-agent/config.json

Override with:

export FITNESS_AGENT_CONFIG_PATH=/custom/path/config.json

The local config stores:

• Strava client id / client secret
• Access token / refresh token / expiry
• Vault path and default vault subfolder

Privacy

Fitness Agent is local-first by design. Activity data and generated notes are written to your machine unless you explicitly publish or sync them elsewhere.

Testing

Run the test suite with:

python3 -m unittest discover -s tests