Open-source gym & body-weight tracker, now in the App Store (iPhone + Apple Watch) and as an Android APK. Plan routines, log workouts, see which muscles are trained, import from Strong/Hevy/FitNotes. Self-host it or use it on the phone alone.
Contributing to openGym
Thanks for taking a look. openGym is deliberately small and light on dependencies, and the aim is to keep it that way: easy to read, easy to self-host.
Project layout
frontend/ React + Vite app (src/views, src/components, src/store, src/lib). Builds to static files.
android/ and ios/ are the Capacitor shells for the phone apps, ios/ with the Apple
Watch app and the widgets (docs/MOBILE.md).
api/ Backend: server.js on plain node:http, three dependencies (@simplewebauthn/server,
web-push, undici). coach/ is the optional AI coach; openapi.yaml documents every route.
web/ Multi-stage Dockerfile (builds the frontend, serves it with nginx) and the nginx template.
mcp/ Optional read-only MCP server for LLM clients (Claude Desktop, Cursor, ...). Not in the
Docker build; it only runs when a client spawns it. See mcp/README.md.
website/ The static project site at opengym.ch.
kubernetes/ Example manifests (docs/SELF_HOSTING_KUBERNETES.md).
docs/ User and operator guides (index: docs/README.md); docs/dev/ has feature design notes.
scripts/ Build and release helpers (scripts/README.md).
catalogue/ The exercise catalogue: one JSON file per exercise, translations in i18n/, and the
licensed 180 px stills and animations in media/ (catalogue/README.md).
The architecture overview explains how the pieces talk to each other.
Running for development
cp .env.example .env
docker compose up -d --build # api + web on :8080
cd frontend && npm install && npm run dev # hot reload, proxies /api to :3000
cd frontend && npm test # training logic, locales, components
cd api && npm test
cd mcp && npm test
Guidelines
- Keep it dependency-light. The frontend uses React, React Router and Zustand (plus the
Capacitor plugins for the phone apps);
api/has three dependencies. A new dependency on either side is a hard sell. - Match the style. Small components, clear names, comments only where the why isn't obvious.
State lives in the Zustand store (
src/store), pure helpers insrc/lib. There is no linter or formatter config, so follow the surrounding code. - Don't commit
data/; it is gitignored. Don't add or replace anything incatalogue/media/: the stills and animations are licensed from Gym visual, 180 px at most, and not open to contributions (see NOTICE.md). - Exercise fixes and translations go through
catalogue/, one JSON file per exercise and one per language. catalogue/README.md explains the fields and how the app is built from them; don't edit the generatedfrontend/src/lib/exercises-data.jsby hand. - Click through what you touched, including the workout flow, in a browser before opening a pull request.
- Training logic gets a unit test. Anything that decides what you lift next, or reads a logged
session back, belongs in a pure helper in
src/libwith a test beside it. These rules are easy to get subtly wrong and nearly impossible to check by clicking; the progression engine has had real bugs that only a test caught. - Some rules exist twice on purpose, once in
frontend/src/lib/and once inapi/(sync, queue, nudge, routine icons), because the API image can't import the frontend. Change both in the same pull request; the list is here. - Leave CHANGELOG.md alone. Release notes are written at release time, from the merged pull requests.
- New UI strings go into every locale in
frontend/src/locales/. English is the source language and has no file.cd frontend && node scripts/check-locales.mjs(run in CI) flags a key that is missing, blank or has lost a{n}placeholder. Portuguese (Brazil) inherits from Portuguese (Portugal) and has its own guard test: a new Portuguese string either gets a Brazilian override or is accepted as shared, thennode scripts/pt-br-inheritance-fingerprint.mjsprints the numbers the test expects.
Using AI tools
openGym itself is developed with Claude Code (see
How openGym is built), and CLAUDE.md holds the
project context for it. You're welcome to use whatever tools you like for a pull request. The bar
is the same either way: you understand the change, it's tested, and you can answer questions about
it in review.
What CI does with your pull request
A pull request runs the three test suites and builds and boots both api image targets. Changes to
the iPhone or Apple Watch app (frontend/ios) can run the iOS workflow too (build, UI tests and the
WatchCore tests on a macOS runner); ask in the pull request if a maintainer should start it. Signed
APKs, TestFlight and App Store builds are made by the maintainer at release time, so if your change
needs a phone build to be judged, say so and we'll put it on TestFlight or send you an APK.
A first-time contributor's workflows wait for a maintainer to approve them, so "no checks yet"
just means nobody has pressed the button.
Merge requests still open on the GitLab mirror are reviewed too and land on main here. New work
should come as a GitHub pull request.
Good first issues
- More starter plans
- Exercise translations: any language in
catalogue/i18n/with gaps, or a new one (see catalogue/README.md) - Percentage or training-max programming (5/3/1 style) on top of the progression engine in
src/lib/progression.js; the policy interface is already there - Accessibility passes on the workout and chart screens
Where to ask what
| You have | Goes to |
|---|---|
| A quick question, or you'd rather chat | Discord |
| A question, or self-hosting that won't behave | Discussions → Q&A |
| An idea you're not sure about yet | Discussions → Ideas |
| A reproducible bug | Issues |
| A change you've already built | A pull request |
| A security problem | Private report, see SECURITY.md |
An answered question in Discussions is worth more than the same answer in a chat log, because the next person searching "passkey login fails behind my reverse proxy" finds it. If a Discord answer turns out to be worth keeping, it belongs in Discussions afterwards.
Reporting bugs
Open an issue with what you did, what you expected, what happened, and your browser and OS. For
login or passkey problems, include your RP_ID and ORIGIN (not the contents of data/); most
login issues are an origin mismatch.
Contributor License Agreement
Before your first pull request is merged, you sign the Contributor License Agreement once, by commenting the sentence the CLA check asks for on your pull request. It covers all your past and future contributions. You keep the copyright in your work; openGym may use and relicense it, which is what keeps the app possible in the App Store and Google Play long term. Every version released under the GNU AGPL v3.0 stays available under it.