Switchback

Switchback is an open-source training companion for ultratrail runners. It reads the training data you choose to connect, retrieves exercise-science guidance, and helps you plan, review, and adapt over a season.

Your watch  →  Intervals.icu / Strava  →  AI agent  →  Switchback
Garmin, Suunto,      training and activity     reasoning and     your training
COROS, Apple Watch   data                       conversation      companion

Quickstart

curl -fsSL switchback.run/install.sh -o /tmp/sb.sh && bash /tmp/sb.sh

The installer creates a local framework and private athlete files, then guides you through selecting an AI agent, connecting Intervals.icu and/or Strava, and setting up your profile. Start a session with switchback.

Also works with Claude Code, Codex CLI, or OpenClaw. More at switchback.run.

Why Switchback

Ultratrail training compounds long-term planning with changing fitness, recovery, weather, work, and family constraints. Switchback turns the resulting stream of workouts, wellness signals, and athlete notes into a durable record that an AI companion can inspect with the runner. Its training framework draws on Training for the Uphill Athlete, Training Essentials for Ultrarunners, Science of Running, and The Happy Runner.

What You Can Do

Morning check-in

> What's on tap for today?

Today's workout: Easy run — 6 mi, Zone 2
Wellness: Sleep 7.2h, HRV 48 (below your 52 avg), resting HR 54
Form: -4 (neutral) — Fitness 42, Fatigue 46

You're slightly fatigued with below-average HRV. Good day for your easy run,
but keep it genuinely easy. If you feel flat in the first mile, no shame in
cutting to 5.

Checking your progress

> How's my training been going?

Looking at the last 14 days:
- Volume: 42 → 51 mi (+21%) — above the 10% ramp guideline
- Sleep: averaging 6.1h (down from 7.3h two weeks ago)
- HRV: 3-day trend declining, now 12% below your baseline
- Form: -18 and falling

This is a yellow flag. The volume jump alone is manageable, but
combined with declining sleep and HRV, you're accumulating more
fatigue than you're absorbing. I'd recommend swapping tomorrow's
intervals for an easy run and prioritizing sleep this week. If HRV
doesn't recover by Friday, consider making this a recovery week.

Race readiness

> Am I on track to run UTMB in 4 months?

Let me pull your data and check...

Based on 12 weeks of training history:
- Current fitness: 52 — you'll want 65-75 for UTMB
- Weekly volume: 45 mi avg — target is 55-65 mi with significant vert
- Vert: 4,200 ft/week — UTMB demands suggest building to 8,000-10,000
- Long run: longest is 3:45 — you'll need multiple 5-6h efforts

You have time, but it's tight. Here's what I'd prioritize over the
next 16 weeks...

Just ask

You can ask your companion anything about your training:

• "Should I run or cross-train tomorrow?"
• "What's my vert progression been like this month?"
• "Is my HRV trend concerning?"
• "How should I fuel for a 50K?"
• "Build me a 12-week plan for a mountain 50K"

Make it yours

During setup, you choose the companion's name, tone, humor, and level of detail. The default name, Virgil, reflects the system's intended role: a guide who explains the terrain and leaves the decisions to the athlete.

Skills (Claude Code)

These slash commands are available in Claude Code. Other agents support the same capabilities through natural conversation — just ask.

Command	Description
/setup	Guided setup — dependencies, API connection, athlete profile, companion persona
/today	Morning briefing — planned workout, wellness, fitness status
/review	Post-workout analysis — planned vs actual comparison and compact activity memory
/archive	Backfill or refresh compact, source-linked activity notes
/week	Weekly summary — mileage, compliance, trend, next week preview
/adjust	Modify upcoming workouts (e.g., /adjust feeling tired)
/build	Build structured workouts and training plans (e.g., /build next week)
/briefing	Post a coaching note to your Intervals.icu calendar
/race	Race-day strategy — pacing, nutrition, aid stations, mental game plan
/nutrition	Post-run nutrition analysis — water, carbs, sodium, caffeine intake
/why	Explain the science behind any training decision (e.g., /why VO2max intervals)
/check	Deep health audit — overtraining signals, volume trends, injury risk

Getting Started

What you'll need

1. A training-data provider — Intervals.icu is recommended for the full experience: it syncs Garmin, Suunto, COROS, Apple Watch, and other devices while providing planned workouts, wellness, and fitness metrics. Strava is also supported as an independent, read-only activity provider for runners who do not use Intervals.icu. Both can be connected together.

2. An AI agent — install at least one of these:

Agent	Install command	Notes
Gemini CLI	npm install -g @google/gemini-cli	Free tier — 1,000 requests/day, no credit card, just a Google account
Claude Code	npm install -g @anthropic-ai/claude-code	Recommended — full experience with slash commands
Codex CLI	npm install -g @openai/codex	Full experience with MCP support

Data providers

Connect either provider during /setup, or connect both. When an activity appears in both services, Switchback treats it as one session and uses the richer source for the question at hand.

Provider	What it provides	What it does not provide
Intervals.icu	Planned workouts and calendar updates; completed activities; training load; wellness; fitness and form trends; weather	Strava activity descriptions, gear, and social context
Strava	Completed activities; athlete-authored activity descriptions; perceived exertion; gear; opt-in streams; on-demand comments	Training calendar writes; wellness; fitness/form metrics

Intervals.icu is recommended when you want calendar planning and readiness-aware advice. Strava is useful on its own for activity review and history, and complements Intervals.icu with the narrative context that athletes often write after a run.

Strava setup

Strava is optional and read-only. Create a personal API application at Strava API Settings, authorize it with read,activity:read_all, and follow Strava's OAuth guide to obtain a refresh token. Add the following only to your local .env file, never to Git or chat:

STRAVA_CLIENT_ID=your_client_id
STRAVA_CLIENT_SECRET=your_client_secret
STRAVA_REFRESH_TOKEN=your_refresh_token

Switchback refreshes short-lived access tokens in memory. The activity:read_all scope is needed to access activities visible only to you. No Strava data is written back by Switchback.

Install

Open a terminal and run:

curl -fsSL switchback.run/install.sh -o /tmp/sb.sh && bash /tmp/sb.sh

The installer will:

• Download the Switchback framework and create a local repo
• Optionally create a private GitHub repo to back up your data (works with Claude Code Cloud too)
• Install everything and set up the switchback command
• Launch your companion for first-time setup — connecting Intervals.icu and/or Strava, building your athlete profile, and choosing a companion personality

It also creates a local .env from .env.example for provider credentials. The file stays outside Git.

After that, just type switchback from anywhere to start a session.

You can also open your private repo in Claude Code Desktop or Claude Code Cloud — it works everywhere.

Updating

At session start, Switchback checks whether an update exists. It changes nothing until you run switchback update. The update is downloaded from the resolved, immutable Git commit and leaves changes uncommitted for review. Athlete files are never overwritten.

How it works

Switchback is not a traditional app — there's no UI or application server. The repository supplies a contract, shared workflow skills, knowledge, and private athlete memory to the selected CLI agent. The agent retrieves current provider data when the athlete's request requires it.

Activity memory

Activity memory is enabled by default. Once per session after activity-related work, Switchback synchronizes completed workouts newer than the last successful sync or latest local record. A post-workout review also stores a compact, source-linked Markdown note in your private athlete/activities/YYYY/MM/ directory. These notes give the companion durable evidence without turning your repository into a copy of a fitness platform. To opt out, set Activity memory to disabled in athlete/profile.md.

Framework operations used by the agents are also available directly:

switchback route "plan race nutrition"
switchback resource read athlete/profile.md
switchback reconcile /tmp/intervals.json /tmp/strava.json
switchback memory sync --intervals /tmp/intervals.json --through 2026-09-08

Each note retains:

• activity source ID, local time, type, tags, distance, duration, elevation, pace, heart rate, load, power/cadence, perceived exertion, and gear when available;
• your activity description when it adds context;
• planned-versus-actual context and an interpretation labeled as a hypothesis or decision.

It deliberately does not copy GPX/FIT/TCX files, raw GPS coordinates, full streams, or friends' comments. GPS and streams can expose sensitive locations and are both large and already provider-hosted. Friends' comments are third-party data: Switchback retrieves them only when asked and never archives them without your explicit instruction.

Synchronization happens only while the companion is active; there is no background daemon. Notes are validated before the synchronization marker advances. On first use, Switchback asks you to choose an initial lookback period, such as 1, 3, 6, or 12 months. It never silently selects how much history to import. /review writes the workout it analyzes, and /archive can backfill or refresh a requested range, for example: archive my trail runs from the last 3 months. See activity-memory.md for the retention policy and the note template for the on-disk schema.

Your personal data (athlete profile, training zones, notes, and companion persona) lives in your private repo and is never shared publicly by Switchback. The CLI model provider receives files and tool results that the agent reads. Review that provider's data policy before use, redact sensitive notes when needed, or use a compatible local model. You can launch Switchback from any machine where you choose to make the private repository available.

Training Philosophy

Three principles guide every recommendation:

1. Health before performance. Long-term health always comes first. Overtraining, under-recovery, and injury risk get flagged — even if it means recommending DNS.
2. Push hard when ready. Within the bounds of health, your companion is direct and demanding. Easy days easy, hard days hard.
3. Evidence over tradition. Recommendations cite physiology and established frameworks. When experts disagree, both approaches are presented with reasoning — you choose.

Knowledge Base

The knowledge/ directory contains reference documents covering training science from aerobic development to race execution and injury prevention. The files distinguish research findings, coaching frameworks, heuristics, and worked examples under the evidence policy. Your companion reads only the chapters relevant to the decision.

Recommended Reading

The training framework draws from these books. We recommend them for any ultrarunner who wants to understand the science behind their training:

• Training for the Uphill Athlete by Scott Johnston, Steve House & Kilian Jornet — Amazon | Evoke Endurance · Uphill Athlete
• Training Essentials for Ultrarunners by Jason Koop — Amazon | jasonkoop.com · CTS
• Science of Running by Steve Magness — Amazon | stevemagness.com
• The Happy Runner by Dr. Megan Roche & David Roche — Amazon | SWAP Running

This project is not affiliated with these authors or organizations. Reading their work remains the best way to understand the training frameworks behind Switchback.

Working with a Coach

Switchback can organize training data, explain a plan, and preserve the context between sessions. A qualified coach can observe form, ask better questions, and adapt to the parts of life that a wearable does not measure. Coaches may also adapt the framework for their own practice; feedback belongs in GitHub Issues.

The authors of the recommended books also offer coaching services:

• Evoke Endurance (Scott Johnston)
• Jason Koop / CTS
• Uphill Athlete
• Steve Magness
• SWAP Running (Dr. Megan Roche & David Roche)

Disclaimer

[!IMPORTANT] Switchback provides educational training support. It does not diagnose or treat health conditions. Consult a qualified healthcare professional about pain, illness, injury, or changes to a training program. You remain responsible for training decisions and trail safety.

License

MIT