Otterpace 🐾
An open-source, AI running coach for iOS — built in the open as a CodeYam showcase.
Otterpace is a friendly running coach in your pocket: it pulls your activity from
Apple HealthKit (or, optionally, Strava), keeps you moving toward your daily 10,000
steps, and gives kind, never-shame-based coaching through Buddy, a
mood-reactive otter mascot.
It's one of the CodeYam showcase apps, alongside
CodeYam Counter and
TabCommand — worked examples built
with codeyam-editor.
Launch
Otterpace is live — available on the App Store.
The end-to-end launch sequence that got us there is preserved as a runbook:
▶ docs/go-live-runbook.md — with a verification check at each phase.
Area deep-dives: site + DNS · AI coach · Strava + analytics · TestFlight prep.
What's here today
The Today dashboard, a native SwiftUI screen that shows:
- A step-goal ring toward your daily 10K, plus active minutes, distance, and
time since you last moved
- Buddy, whose mood (resting → ready → jogging → cheering → concerned →
celebrating → recovery) reflects how the day is going
- An AI coach card with one clear, practical recommendation — conservative and
load-aware, flipping to an amber caution when your training load spikes
- Your latest run/walk and a weekly training-load snapshot
- A friendly day-one "Connect Apple Health" hero for first launch
The Ask Coach chat, reached from a Today/Coach tab bar or the
"Ask Buddy" button on the coach card:
- Ask Buddy a fitness question and get a practical, load-aware reply —
"Can I run or should I rest?", "How do I hit 10K without overdoing it?",
"Am I increasing mileage too fast?", or "my knee hurts after my run"
- Replies are classified by intent and built from your own activity context,
so they feel personal — a recent hard run or spiking load steers Buddy toward
recovery, and pain questions return a non-diagnostic, see-a-clinician answer
behind an amber "safety first" shield
- A real AI coach is available when you connect your own API key from
Anthropic, OpenAI, or Gemini (the provider is recognized from the key's shape,
so there is nothing to pick)
(Settings → AI Coach): questions go to a Vercel backend that calls Claude with
the load-aware coach prompt. Without a key — and offline, or in scenario
previews — the deterministic
CoachEngine
(Sources/AppCore/CoachEngine.swift) answers, so the coach always works and
captures stay reproducible
The Weekly Review, opened from the Coach tab — a read-only recap the coach
generates from your weekly training load: what went well, what changed, training
risk, suggested next week, and one focus area, with Buddy's mood and an amber
safety callout when load spikes. Built by the deterministic WeeklyReviewEngine.
The Activity History, opened from the Today dashboard — recent
workouts grouped by week, each week fronted by its mileage / run-count / rest-day
rollup, with a friendly empty state for day one. Grouping is the testable
ActivityHistory.groupByWeek.
Settings, reached from the gear on the dashboard, gathers the account and
integration controls:
- Sign in with Apple (optional) — no account is required to use Otterpace; if
you sign in, only an anonymous identifier is kept in the Keychain. Sign out
and delete account both live here (the App Store account-deletion requirement).
- Apple Health — connect / disconnect with a live status row.
- Strava (optional) — connect to import your runs and rides as an alternative
to Apple Health. OAuth runs through a small backend so the client secret stays
server-side; the Strava tokens never touch the device.
- AI Coach — paste your own key from Anthropic, OpenAI, or Gemini to upgrade Buddy from the built-in
coach to a real model (see Ask Coach above).
- Movement reminders — optional on-device notifications: a daily nudge at a
time you choose, an evening goal nudge, and an inactivity nudge.
- Your editable daily step goal and a short privacy explainer.
The whole UI scales with Dynamic Type and meets WCAG AA contrast, and the app
ships a code-generated app icon (see below).
The Today screen is driven by a single TodayState (see Sources/AppCore/Model.swift),
populated from HealthKit (or imported Strava activity) in the real app and from
each CodeYam scenario's deviceState preferences in the simulator preview.
Production starts empty; each scenario carries its own seeded state.
Built with CodeYam
Otterpace is a worked example of building a native iOS app with the CodeYam
editor — a scenario-driven loop where every feature is developed against
seeded, captured states that render in a live simulator preview.
The core idea: a single TodayState (Sources/AppCore/Model.swift) drives the
UI, and each scenario (.codeyam/scenarios/*.json) seeds that state at launch
through a deviceState.preferences map (the rb* / otterpace* UserDefaults
keys) injected into the simulator. "Goal Crushed", "Recovery Caution", and
"Day One — Connect" are the same screens rendered from different seeds, each
captured as a screenshot the editor verifies.
Two patterns keep that loop reliable:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
