Skip to content
Back to search

rep

Offline-first gym tracker: weekly streaks, exercise guides with video, and an MCP server for your AI coach.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ilmal--rep/badge.svg)](/listings/ilmal--rep)

HTML

<a href="/listings/ilmal--rep"><img src="/api/listings/ilmal--rep/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 184 lines
  1. <div align="center">
  2. # Rep
  3. **A gym tracker that thinks in weeks, works without a signal, and takes direction from your AI coach.**
  4. [**Open the app**](https://rep.ilmal.se/app/) &nbsp;·&nbsp; [Website](https://rep.ilmal.se) &nbsp;·&nbsp; [Connect a coach](#a-coach-that-can-actually-change-things) &nbsp;·&nbsp; [Run it yourself](#run-it)
  5. <br>
  6. <img src="docs/screenshots/hero.png" alt="Rep on a phone: Today, Streak, an exercise guide with video, and a live set" width="100%">
  7. </div>
  8. <br>
  9. Most trackers ask you to follow a calendar. Rep asks one question: *did you train enough this week?* You set a weekly goal, it
  10. builds each session from your gym's equipment and your recent history, and it quietly keeps score so the next session is a little
  11. better than the last. It installs to your home screen, works in a basement gym with no reception, and syncs when you're back online.
  12. ## What it does
  13. **Train by the week, not the calendar**
  14. Pick how many sessions a week you want. Sessions are built around body areas that rotate, so you never think about "what day is leg day".
  15. A streak counts the weeks you hit your goal, with repairs and freezes so one rough week doesn't erase a good run.
  16. **Knows where you are and what's there**
  17. Add your gyms with the equipment each has. Rep matches your GPS to a gym, only suggests what you can actually do, and swaps an exercise
  18. in one tap when a rack is taken. Training at home with nothing? There's a built-in no-equipment location with a bodyweight catalog.
  19. **A planner that explains itself**
  20. Every exercise is scored on relevance, recency, frequency and muscle coverage, with cooldowns and a variety penalty. You can see why
  21. something was picked, favourite or ban lifts, and tune every weight. After each exercise you say whether the weight felt light, right or
  22. heavy and the next session adjusts.
  23. **Learn the lift before you do it**
  24. All 108 exercises come with a summary, numbered steps, coaching cues, things to watch for, and a demo video that plays right in the app.
  25. Edit any of it, or let your coach write the notes that matter to you.
  26. **Pulse, if you want it**
  27. Turn on heart rate and your iPhone sends readings from Apple Health (AirPods Pro or Apple Watch) in the background. You get a live pulse chip on the workout screen, zone colours, and average, max and min in every session summary. Outside workouts you choose how often a reading arrives. Your coach can read it too.
  28. **Streaks that earn their keep**
  29. Four tiers, milestone badges, streak freezes you earn every four goal weeks, a 30-minute express session when the week is slipping, and
  30. reminders that stay quiet at night.
  31. **Yours, and fast**
  32. Offline-first: everything is written to the device first and synced in the background. A workout survives a dropped connection, a
  33. reload, or the phone being killed mid-set.
  34. <br>
  35. <table>
  36. <tr>
  37. <td align="center" width="25%"><img src="docs/screenshots/today.png" alt="Today screen with a streak at risk and one-tap plan"><br><sub><b>Today</b><br>the week at a glance</sub></td>
  38. <td align="center" width="25%"><img src="docs/screenshots/live-set.png" alt="Logging a set"><br><sub><b>Live session</b><br>big targets, one thumb</sub></td>
  39. <td align="center" width="25%"><img src="docs/screenshots/guide.png" alt="Exercise guide with an inline video"><br><sub><b>Exercise guides</b><br>steps, cues, video</sub></td>
  40. <td align="center" width="25%"><img src="docs/screenshots/badges.png" alt="Badge collection"><br><sub><b>Badges</b><br>milestones worth chasing</sub></td>
  41. </tr>
  42. <tr>
  43. <td align="center"><img src="docs/screenshots/streak.png" alt="Streak screen"><br><sub><b>Streak</b><br>pace, freezes, history</sub></td>
  44. <td align="center"><img src="docs/screenshots/progress.png" alt="Progress screen"><br><sub><b>Progress</b><br>what is actually improving</sub></td>
  45. <td align="center"><img src="docs/screenshots/plan.png" alt="Plan screen"><br><sub><b>Plan</b><br>areas, rotation, planner</sub></td>
  46. <td align="center"><img src="docs/screenshots/library.png" alt="Exercise library"><br><sub><b>Library</b><br>everything, searchable</sub></td>
  47. </tr>
  48. </table>
  49. ## A coach that can actually change things
  50. Rep runs an [MCP](https://modelcontextprotocol.io) server at `/mcp`. Create a token under **Settings → Connect a coach** (read-only or
  51. read & write) and point any MCP-capable agent at it. It can read your history, explain a score, preview the next session, rewrite your
  52. plan, adjust planner weights, write exercise guides and attach videos, and use or undo a streak freeze, all of it landing in the same
  53. sync stream as the app, so your phone picks the changes up on its own. More than 40 tools, listed [below](#connect-a-coach-agent-mcp).
  54. ## Built like it matters
  55. - **Domain logic is pure and shared.** Planner, progression, streaks and sync rules are plain TypeScript in `src/shared`, used by the
  56. app and the server alike, so they cannot drift apart.
  57. - **Streaks are derived, never stored.** The whole streak, freeze and badge state is recomputed by deterministic replay from your
  58. sessions and settings, which makes it testable to death (property tests included) and impossible to corrupt.
  59. - **Tested hard.** ~1,000 unit and property tests, ~850 Playwright end-to-end tests run against the production build, and mutation
  60. testing on the streak and content engines (95% and 97% of mutants killed).
  61. - **Small and boring where it counts.** One Bun process serves the landing site, the app, the API and MCP. SQLite in WAL mode, hourly
  62. verified backups copied off the machine, graceful shutdown, a queue for outgoing mail. See [docs/SCALING.md](docs/SCALING.md) for
  63. what scales, what doesn't, and the exact signal that says when to change it.
  64. | | |
  65. | --- | --- |
  66. | App | React 19, React Router, Vite, a hand-rolled offline store (IndexedDB + outbox, last-write-wins sync) |
  67. | PWA | Service worker with an update prompt, installable on iOS and Android, wake lock, app badge, web push |
  68. | Server | Bun, Hono, `bun:sqlite`, streamable-HTTP MCP |
  69. | Mail | Amazon SES over a hand-signed SigV4 request (no SDK), Resend as a fallback |
  70. | Quality | `bun test`, Playwright, StrykerJS, fast-check |
  71. ## Run it
  72. ```bash
  73. bun install
  74. bun run dev:server # API + MCP on :8787 (data in ./data/gym.db)
  75. bun run dev:client # Vite on :5173, proxies /api and /mcp
  76. bun test src # unit + property tests
  77. bun run build && bun start # production: the server also serves ./dist
  78. ```
  79. Geolocation and installing the PWA need HTTPS (or `localhost`).
  80. Docker: `docker build -t rep . && docker run -p 8787:8787 -v rep-data:/data rep`.
  81. Optional environment (all unset by default, nothing is required to run locally):
  82. | Variable | Purpose |
  83. | --- | --- |
  84. | `PUBLIC_URL` | Public origin, used in sign-in links and the push subject |
  85. | `SES_ACCESS_KEY_ID`, `SES_SECRET_ACCESS_KEY`, `SES_REGION` | Send sign-in email through Amazon SES |
  86. | `RESEND_API_KEY` | Or send it through Resend |
  87. | `MAIL_FROM` | Sender, e.g. `Rep <login@your-domain>` |
  88. | `GYM_DB` | SQLite path (default `./data/gym.db`) |
  89. Without a mail provider the sign-in link is printed to the server log in development. There are Kubernetes manifests, a smoke test and a
  90. backup restore drill in [`deploy/`](deploy), and the hardening notes live in [`docs/SCALING.md`](docs/SCALING.md).
  91. ## Architecture
  92. - `src/shared` — pure domain code (incl. `content.ts` how-to content: limits, media URL detection, sanitising, merged view; `exercise-content.ts` built-in text) used by the client AND the server: types, equipment catalog, exercise library, `rules.ts`
  93. (progression, auto-adjust, hot-swap scoring, week counter, rotation pointer, geo), `planner.ts` (exercise scoring + session generation).
  94. - `src/server` — Hono on Bun. `api.ts` (anonymous device accounts, optional email+password, push/pull sync with last-write-wins per entity,
  95. export/delete, API tokens), `mcp.ts` (MCP over streamable HTTP), `store.ts` (entity access). SQLite via `bun:sqlite`.
  96. - `src/client` — React + react-router. `store/` is an offline-first store persisted to IndexedDB with an outbox that syncs when online.
  97. All timers derive from wall-clock timestamps and the in-progress session is persisted, so a reload or kill resumes cleanly.
  98. ## Scoring (what the planner does)
  99. Every exercise gets a 0–100 score on each planning run:
  100. `(wRelevance·relevance + wRecency·recency + wFrequency·frequency + wCoverage·muscleCoverage + wFavorite·favorite) / Σw`, minus 40 while cooling down.
  101. - **relevance** (0–100): yours / your coach's rating of how relevant the exercise is to the current plan.
  102. - **recency**: rises the longer since you did it; 0 while cooling down (not repeated within `cooldownSessions` sessions or `minDaysBetween` days).
  103. - **frequency**: favours exercises you've done less within the window.
  104. - **coverage**: favours exercises whose muscles are overdue (and that fit the area's focus).
  105. Selection is greedy with a variety penalty, so similar-but-different exercises rotate in instead of the same lift twice.
  106. `avoid` excludes an exercise from auto-picks; pinned exercises are always included. Every knob is in Settings → Planner and editable over MCP.
  107. ## Streaks and rewards
  108. Streak = consecutive Mon-Sun weeks that count (hit, repaired, frozen); repair a week missed by 1-2 next week, earn a freeze per 4 weeks (max 2), tiers and 18 badges.
  109. All of it is derived from sessions + settings by `src/shared/streak.ts` (API documented at its top; rules and states in `docs/STATES.md` 3.1), so the app, MCP (`get_streak`) and push reminders agree.
  110. ## Connect a coach agent (MCP)
  111. In the app: **Settings → Connect a coach** → create a token (read-only or read & write). Server URL: `https://<your-host>/mcp`
  112. (streamable HTTP, JSON responses, `Authorization: Bearer rep_…`). For a client that takes a URL plus an auth header:
  113. ```json
  114. { "type": "url", "url": "https://<your-host>/mcp", "authorization": "Bearer rep_XXXXXXXX" }
  115. ```
  116. Smoke test:
  117. ```bash
  118. curl -s https://<host>/mcp -H 'authorization: Bearer rep_…' -H 'content-type: application/json' \
  119. -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_overview","arguments":{}}}'
  120. ```
  121. Exercise guides: every exercise (built-in and custom) has how-to content: summary, ordered steps, coaching cues, good-to-know tips and images/videos. Built-ins ship written text plus one demo video that plays inside the app; your own edits and your coach's are stored as an override on the exercise's pref, win per field, and sync like any other preference (see `docs/STATES.md` 1.5.1). The athlete reads it on the exercise page, from "How to do it" on the live "Up next" screen and from the info button in the pre-session list. Over MCP: `get_exercise` / `list_exercises` return the merged content (`content.customised` says which fields are yours; `missingUserContent` finds undocumented exercises), `set_exercise_content` (replace or merge steps/cues/tips/summary), `add_exercise_media` (https image, video file, YouTube/Vimeo link; kind auto-detected), `remove_exercise_media`, `reset_exercise_content`, plus content fields on `create_exercise`/`update_exercise`. The coach is told to write the most important parts the athlete should read before performing the exercise; media URLs must be https and are never invented. The server sets a CSP on `/app/*` allowing images/video over https and YouTube-nocookie / Vimeo embeds only (the player loads after a tap).
  122. Read tools: `get_overview` `list_sessions` `get_session` `get_exercise_history` `list_exercises` `get_exercise` `explain_score` `list_areas` `list_gyms`
  123. `list_equipment_catalog` `get_settings` `get_muscle_report` `get_stats` `get_streak` `get_heart_rate` `get_session_heart_rate` `preview_next_session` `list_coach_plans` `list_events` `export_all`.
  124. Write tools: `create_exercise` `update_exercise` `archive_exercise` `set_exercise_pref` `set_exercise_content` `add_exercise_media` `remove_exercise_media` `reset_exercise_content` `bulk_set_exercise_prefs` `set_next_prescription` `create_area` `update_area`
  125. `delete_area` `set_rotation` `update_settings` (incl. planner weights and profile notes) `reset_planner` `use_streak_freeze` `undo_streak_freeze` `update_gym_equipment` `create_coach_plan` `cancel_coach_plan` `add_session_note`.
  126. The built-in location `gymId: "none"` ("At home, no equipment": bodyweight, floor, wall) is always available and not a stored gym: `preview_next_session` and `list_exercises` (`availableAtGymId`) accept it, sessions there read `gym: "No equipment"`, and `update_gym_equipment` refuses it.
  127. Writes land in the same sync stream as the app, so the phone picks them up within about a minute (or on next open).
  128. ## Data & privacy
  129. Anonymous device account by default; optionally add email+password to restore on another device. Export and delete live in Settings.
  130. API tokens are stored hashed; passwords use argon2id (`Bun.password`).
  131. ---
  132. <div align="center"><sub>Made for lifting heavy things on a schedule that survives real life. &nbsp;·&nbsp; <a href="https://rep.ilmal.se">rep.ilmal.se</a></sub></div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.