running-coach

running-coach

Adaptive running training plugin for Claude Code. Generates a personalized macrocycle from your race goal, prescribes daily workouts using Daniels' VDOT pacing, and iterates the plan after every workout based on actual performance.

What it does

• Set a race goal with target date and current fitness baseline
• Get a complete training plan (base → build → peak → taper) generated from Daniels' VDOT methodology and polarized 80/20 intensity distribution
• See today's workout card with target paces, RPE expectations, and warm-up cues
• Log each workout manually or sync automatically from Strava (optional)
• The plan adapts after every workout: 2 missed targets → reduce next quality session; 3 misses → recovery week; 3 on-target → VDOT bump
• Weekly review surfaces fatigue trends and recommends hold / advance / recovery

Quick start

# 1. Install (drop the directory into your plugins folder)
# 2. Open Claude Code in any working directory
# 3. Run the onboarding interview
/run-init

# 4. Each morning
/run-today

# 5. Each evening after running
/run-log

# 6. Each Sunday
/run-week

Commands

Command	What it does
/run-init	One-time onboarding: goal, fitness, training days, lifestyle
/run-init --connect strava|garmin	Onboarding + probe and connect Strava or Garmin Connect account
/run-today	Show today's workout card
/run-log [date]	Log a completed workout (triggers adaptive iteration)
/run-sync [--days N]	Pull recent Strava or Garmin Connect activities (requires /run-init --connect strava|garmin)
/run-week	Weekly rollup + recovery decision
/run-replan [--reason "..."]	Force full plan regeneration
/run-plan	Show current macrocycle (read-only)
/run-race-recap	Post-race log + VDOT update + 4-day rest protocol
/run-research "question"	Web-search-backed coaching Q&A

How adaptive iteration works

After each workout, analyze-workout computes the delta between actual and prescribed: completion %, pace delta %, RPE delta, intra-session HR drift. The verdict (on-target / under / over / aborted) drives a strike-rule engine:

• 1 missed target — monitor, no plan change
• 2 consecutive misses — next quality session intensity reduced one step
• 3 consecutive misses — recovery week inserted (volume −30%, drop one quality)
• 3 consecutive ahead-of-target — VDOT bumped, remaining plan paces regenerated
• Aborted with high HR drift + high RPE — fatigue red flag; second occurrence in 14 days triggers recovery week

See docs/methodology.md for the full coaching rationale and DESIGN.md for architecture details.

---

Connecting an activity source (optional)

Activity source integration lets /run-sync automatically import your runs without manual entry. Manual logging via /run-log works perfectly without it — both Strava and Garmin are opt-in and the plugin remains fully usable with no MCP configured.

preferred_source semantics: The most-recently-connected provider becomes preferred. On same-date duplicates, the preferred source wins and the other entry is kept but marked superseded_by the winning entry's ID.

Strava

When connected, /run-sync fetches your recent Strava activities, normalizes fields (pace, HR, splits, RPE from description), deduplicates against existing log entries, and runs the same analysis and adaptation pipeline as manual logging.

Setup steps:

1. Install the Strava MCP server Follow the instructions at https://github.com/r-huijts/strava-mcp to install r-huijts/strava-mcp.

2. Create a Strava API app Go to https://www.strava.com/settings/api, create an app, and note the Client ID and Client Secret. Follow the OAuth flow in the MCP server README to generate a Refresh Token.

3. Set environment variables in your MCP config Add the following to your Claude Code MCP server configuration (see https://docs.anthropic.com/en/docs/claude-code/mcp):

   • STRAVA_CLIENT_ID
   • STRAVA_CLIENT_SECRET
   • STRAVA_REFRESH_TOKEN

4. Probe and connect Restart Claude Code (so the MCP server loads), then run:

   /run-init --connect strava
   

   The plugin probes the MCP server and your credentials before writing anything. On success you'll see: "Connected as @{username}."

Troubleshooting: