Liftgeist · blog

Build log

Training that keeps the receipts

I built a free workout and macro tracker in six weeks because three apps could not answer one question. Here is how it works, what it runs on, and everything that broke.

Why I built it

A lifting app, a macro tracker and a weigh-in app cannot tell you whether the extra food moved the lifts. Each one keeps its own history, in its own format, behind its own subscription, and the one question I actually wanted answered falls into the gap between them. Did the heavy week and the hungry week happen together? Did bodyweight go up because the bench did, or instead of it?

So I wrote a tracker that keeps all three in one ledger. Every set you log, every meal you photograph and every morning weigh-in lands in the same history, keyed by the same dates, charted against each other, and exportable as a file you own.

It did not start as a product. The first commit, on 28 June 2026, is a single 3,130-line index.html called Lift Log: a vanilla single-file web app with Supabase sync bolted on, built for me and a friend. His six-month spreadsheet program is still hard-coded into the legacy file as an onboarding template, under a comment labelled Gio beta. The local storage key still carries the name of the original goal, which was abs by August. Make of that what you will.

The React and Vite rewrite started the next day, with a build-time check that fails the deploy if the storage key, the cache rules or a single line of the data migration drift from the original file, because real people already had data in it. Capacitor came the same day. The name went from Lift Log to RepLedger to Liftgeist inside ten days. Six weeks and 288 commits later it is a web app, an iOS app, an Android app, an Apple Watch rest timer, a web dashboard and a 448-program catalog with an AI coach in front of it.

The tracker's job is not to motivate you. It is to never lose a set, never lie about a number, and never change your plan without telling you.

What it looks like

These are real screens from app.liftgeist.com. The first three are the product screenshots from the landing page, a ledger with several weeks of history; the rest were captured in guest mode on a phone-sized viewport.

How workout generation works

There are three ways a program gets into Liftgeist: pick one from a written catalog, describe what you want and let Claude design it, or upload someone else's plan. All three produce the same shape and flow through the same pipeline, so a program built by the AI and a program pasted from a PDF are indistinguishable once they are a cycle.

The catalog: 448 written cycles

Nobody typed 448 spreadsheets. The catalog is compiled from a compact, normalized library of training building blocks, with citations behind the numbers, and a set of rules for assembling them into weeks and progressing them across a block. Pick a style of training, a length, a weekly frequency and your equipment, and the app resolves the matching cycle on the spot.

Fully expanded, the 448 programs run to many megabytes. The app does not ship that. A build step extracts only the parts that are authored rather than derivable, then does the thing that lets me sleep: it resolves every program through the same code the app uses and deep-compares the result against the fully expanded reference. A mismatch fails the build. "Smaller" can never quietly become "different".

Every week also knows where it sits in the block. A deload renders lighter than the weeks around it, an overload week sits closer to failure, and the schedule logic is smart enough that a three-day push/pull/legs block is not the same three days forever.

The AI builder: the note is the spec

You write one note. "Build muscle, 4 days a week for an 8-week block, full gym, and bring up my bench." That note goes to a server-side function, so the API key never touches the phone, and runs through two stages of Claude.

Stage one reads the note against a strict schema and returns what it could infer: goal, days, weeks, equipment, plus a coaching guess for anything missing. The picker screen only appears for the fields the note did not cover, pre-filled with those guesses, so it is usually one tap.

Stage two writes the cycle. The system prompt is long, and the part that took the most iteration is the part that stops the model from being helpful in the wrong direction. The generator treats the note as a specification, not a suggestion. If you name a split, you get that split, even when the day count divides awkwardly; push/pull/legs on five days means two of the sessions come twice, and the program says which. A priority lift leads a day and gets extra volume. An injury swaps out the hostile patterns, and the progression line says why. Equipment limits, schedule quirks, sports and dislikes all have to be visible in the exercise selection, the ordering and the session names. The week repeats, because that is what a cycle is. And a generic template that satisfies the structure but ignores the note counts as a failed response, not a program. What comes back is parsed and checked before it is allowed to become a cycle.

A few details that matter more than they look:

• Exercise names come from a pool, not from the model's imagination. The pool is built from a public-domain exercise database (873 movements), filtered by your equipment, and names have to come back exactly as given, because the form-guide demos are matched by name and a paraphrased name silently loses its demo.
• Less thinking, faster programs. Thinking tokens and output tokens share one budget, and an early version let the model think at length before writing. In one memorable failure it spent most of the budget thinking and then truncated the program mid-array. The prompt is prescriptive enough to hold the split without it, and turning it off took generation from nearly two minutes to about twenty seconds.
• Web search only for named published programs. If you ask for 5/3/1 or GZCLP the model can look it up. For an ordinary split it does not, because that was the other half of the latency.
• Every AI call has an offline fallback, and the fallback is labelled. If the server is unreachable, an on-device generator builds a sensible program from the basics. It never reads your note, so the result is tagged BUILT OFFLINE with a warning and a retry button. An unlabelled fallback reads as the AI ignoring you, which is worse than the AI being down.

The readiness check-in: never silent, deload protected

Before a catalog session, a slim row asks whether you are feeling off. Four questions, sleep, soreness, stress and energy, scored and weighted rather than simply averaged. The answer lands in one of three outcomes: run the day as written, trim the edges, or cut it back. Sharp or joint pain short-circuits everything and routes to substitute-or-stop, with no "run it anyway" button on purpose.

The questions, the weights, the rules and the exact sentences the app says are data, not code; the code is arithmetic and a rule matcher, and the data can be tuned without touching it. Two guardrails are enforced in code rather than trusted to the data: a planned deload is never cut further, whatever the score says, and the movements the session exists for keep their sets no matter what, because dropping the main work and keeping the arm work inverts the whole point.

The adjustment is applied over the written day and stored as a fact about that date. The program itself is never modified, which is why the strip on the Train screen reads "trimmed for today · your program is unchanged".

Week pinning: the plan can never contradict history

The moment you finish a session, that week is frozen into its own copy, with your logged sets still linked to it. Exercise edits land on the week you are looking at, and changes to the shape of a day apply forward, never to a week that is already in the books; that killed an old bug where editing week 7 also rewrote week 6. Sessions keep a stable identity across weeks, so "Push A" in week 5 knows it is the same session as "Push A" in week 1, and "what did I lift last time" is a lookup, never a guess.

The coach, and importing someone else's program

The in-app coach is the same model with a compact snapshot of your actual data: program and goal, bodyweight trend, today's sets so far, this week's and next week's plan with the phase line, all-time PRs with estimated 1RMs, nutrition versus targets, and your recent check-ins. It is told to quote the specific number and to say plainly when the data is absent. It can act, through four tools (log bodyweight, log a meal, log sets, adjust one exercise on today's day), but the server never executes anything. The app validates the call, shows a confirm card, validates again when you accept, and if you decline, the model is told so in no uncertain terms. It then confirms in the unit the app actually recorded, 166.9 lb rather than the 75.7 kg you said.

Importing works the same way in reverse: a handful of screenshots, a PDF or a CSV of any plan go to the model with one instruction, use the exercise names exactly as written and never swap in your own picks. The output is the same shape the builder produces, so it becomes a cycle through the same code path.

Macro and calorie tracking

The food side is called Fuel, and it lives in the same ledger as the training, not in a second database. That one decision is most of the product: meals, sets and weigh-ins share the same dates, a single sync path, the same delete-protection and the same export.

Type it, photograph it, scan it

Logging a meal is one full-screen sheet. You can search (your own history first, then about 5,000 USDA foods, then branded products from Open Food Facts), describe the meal in a sentence (or dictate one with your keyboard), attach a photo, scan a barcode, or any combination. "Estimate macros" sends the note and the photo to Claude and gets back a strictly shaped answer: a meal slot plus items, each with a human-readable portion and whole-number calories, protein, carbs and fat.

The model is held to the arithmetic, so the calories have to agree with the macros; it assumes normal adult cooked portions; and when both a note and a photo arrive, the note decides what and the photo decides how much. Nothing saves without passing through a review screen where every number is editable, and the AI items carry an "AI estimate" pill with the line "close enough to track trends, not lab-exact". If the network is down you drop into manual entry; the sheet never blocks.

Two small mechanics do a lot of work. Rescaling is grams-first: every portion that starts with a number gets an amount control, and the macros recompute from a stashed base rather than the last rounded values, so typing digit by digit never accumulates drift. And corrections are memory: if you hand-edit the chicken breast, the next estimate for "chicken breast" starts from your numbers, not the model's. Barcode scans bypass that memory on purpose, because a label is authoritative.

The barcode scanner runs in the browser, lazy-loaded so it stays out of the main bundle; the first hit goes to Open Food Facts, and the label's per-100 g values become a "125 g" portion you can rescale like anything else.

Targets: calories are computed, never typed

Targets are opt-in. With no goal set, Fuel is an intake-only ledger with no rings and no "remaining" math. When you do set a goal (cut, maintain, lean bulk), the sheet needs your bodyweight, and for a cut or bulk a goal weight on the correct side of it. It refuses to compute without a bodyweight, because a formula that does not know the person can only guess, and a guessed target is worse than none. There is a bug behind that rule: Number(null) is 0, and an early version clamped that into a 60 lb person with an 800 kcal target.

Maintenance is sized from bodyweight and how often you train, the deficit or surplus from a safe weekly rate toward the goal weight, protein and fat from bodyweight, and carbs fill the rest. The model writes a short note in the house voice; the server clamps whatever it says to a calorie floor that no goal is allowed to push below. If the network fails, a local version of the formula runs with fixed constants.

Whatever the source, the calories you see are never a typed number. The Calories field is read-only and equals p × 4 + c × 4 + f × 9; editing a macro moves the calories and the "about N weeks to X lb" line, and carbs are the balancing term. Calories and macros can therefore never disagree with each other.

One ledger

The entire account is one ledger. Training logs, freestyle sessions, bodyweight and waist check-ins, meals, per-food correction memory, deletion records and targets live together, saved on the device first and, when you sign in, synced to the cloud as one unit. That is why the You screen can put protein per pound of bodyweight next to this cycle's tonnage, and why the web dashboard can overlay a bodyweight line on the calorie bars with a single toggle. It is also why the calorie bars are coloured by macro composition: each bar is drawn as stacked calorie contributions at 4/4/9, so its colour split is its macro split, with a neutral remainder so the height still equals what you actually ate.

If you are coming from another tracker, the web dashboard imports your nutrition and bodyweight history from a MacroFactor export (and Cronometer, MyFitnessPal, Lose It, or any CSV). The importer is deliberately not a MacroFactor-shaped parser: it scores every column header against a synonym table, shows you the mapping to correct, refuses to let "Calcium" become calories, "Fat Percent" become dietary fat or "Serving Weight (g)" become bodyweight (the last two found on real exports), and resolves conflicts per meal slot with "fill the gaps" as the default, the only mode that cannot change a day you already recorded. MacroFactor's scale export is .xlsx, so there is a tiny zip-and-two-XML-parts reader for that rather than a 400 KB spreadsheet library.

How it compares

Every figure below was checked on 21 August 2026 against the vendor's own pricing or help pages, or, where a help center blocks automated reads (MyFitnessPal, Hevy, Cronometer), against search snippets of those same pages. US prices. They are all good apps; the point of the table is the shape of the gap, not a scorecard. Liftgeist wins on exactly one axis, lifts and food in one free ledger, and is honestly behind on others: no store listings yet, and no social feed, friends or leaderboards if that is what you want out of a training app.

Sources: macrofactor.com, help.macrofactorapp.com, myfitnesspal.com and its support center, the US App Store listings for Strong, Hevy and Liftosaur, help.strongapp.io, help.hevyapp.com, cronometer.com, liftosaur.com. Every vendor sets regional prices.

Two things I want to be fair about. Hevy imports Strong's CSV and Liftgeist does not import workout history from anyone yet, only nutrition and bodyweight; that is next. And Cronometer's free tier is genuinely generous, including the barcode scanner. None of the apps in the table puts the lifts and the food in one history with one export, for free, in a browser, with no account. That is the whole bet.

The tech stack

One codebase, four surfaces. I tried to pick boring, cheap pieces and spend the complexity budget on the parts users feel: sync that never loses a set, updates that actually land, and a rest timer that buzzes on time.

One deployment

The marketing site and the app are one deployment, and the landing page is deliberately not the app's entry file. The reason is the kind of thing you only learn by almost doing it: the installed apps boot the same entry file the web serves, and every update bundle is a copy of the web build. Rename that file and every phone boots into a marketing page after its next update.

Sync: local first, then everywhere

Every state change is written on the device first, mirrored into native storage on iOS for reasons you will read below, and pushed to the cloud on a short debounce; anything structural flushes immediately. Pushes are serialized so two saves can never commit out of order, and every call has a timeout so a stalled request can never hang the app.

Cross-device freshness has two layers. After a successful push, the device sends a tiny "something changed" ping on a per-user channel, and the other devices re-pull. I used a ping rather than streaming the data itself because the ledger syncs as one unit, and shipping the whole thing to every listener on every save would be absurd. Then, because a websocket can die silently, a periodic heartbeat asks the server whether anything changed and pulls only when it did.

Self-hosted OTA

Every production build publishes an update bundle alongside the site, built reproducibly so that identical code never looks like a new update, and a build id surfaced in Settings tells you exactly which bundle a phone is running. Getting that reproducible was most of the work: the version was a hash of the zip, and the zip carried its entries in whatever order the filesystem handed them over, so the same commit hashed differently on a Mac than on the Linux box that builds the site. The mechanism is built and switched off. The App Store wants the binary it reviewed to be the binary that runs, which is a fair thing to want, so installed apps update through the App Store and the bundle machinery sits behind a single flag until there is a reason to turn it on.

The watch, and the one formula

The phone is the source of truth; the watch and the lock screen are mirrors driven by timestamps, never ticks, so a missed update cannot drift a clock. Every payload to the watch is the full session state with a monotonic sequence number; the watch drops anything stale, re-arms its alarm only when the deadline actually moved, and applies wrist commands (skip, plus or minus 15 seconds) locally first. An HKWorkoutSession keeps the watch app executing with the screen off, which is the free-tier way to get a sub-second haptic. The Live Activity puts the same timer on the lock screen and, on iOS 18, in the watch's Smart Stack.

And every strength number in the app comes from one function. Epley, nothing fancy, with a PR flagged when today's best estimate beats the prior best across every cycle by more than half a pound.

export function e1rm(weight, reps) {
  const W = parseFloat(weight);
  const R = parseFloat(reps);
  if (!Number.isFinite(W) || !Number.isFinite(R)) return null;
  return W * (1 + R / 30);
}

The web dashboard is built from the same codebase and imports the app's model directly, so volume, PRs and streaks have exactly one definition. It exists for the things a phone screen is bad at: months of calorie bars with a bodyweight line over them, a CSV import you are correcting column by column, a PR table you actually want to read. Same account, same ledger, and it sees what the phone wrote seconds after it was written.

Problems I ran into

Six weeks, 288 commits, and a lot of them are fixes. These are the ones I would want to have read before starting.

private func fire() {
    timer = nil
    let deadline = armedFor
    armedFor = nil
    let center = UNUserNotificationCenter.current()

    // Overdue by more than a moment means the deadline passed while this
    // process was suspended and the timer only ran now. The rest is long
    // over and the backstop notification already carried it; buzzing here
    // would land mid-set. Tolerance covers ordinary queue latency, not a
    // resume from suspension.
    guard let deadline = deadline, deadline.timeIntervalSinceNow > -2.0 else {
        // Deliberately does NOT cancel the backstop here. Layer 1 has just
        // declined this rest, so the notification is the only alert left
        // for it. In practice it already fired at deadline+2s while this
        // process was suspended, making a cancel a no-op; if it is somehow
        // still pending, letting it ring is the correct outcome.
        return
    }

await activity.update(ActivityContent(state: state, staleDate: end.addingTimeInterval(1)))

What makes it free, and different

Free means free. Logging sets, logging meals from a photo or a sentence, barcode scans, the 448-program catalog, the AI builder, the coach, PR flags, strength charts, bodyweight, every theme, a JSON backup of everything. In a browser, today, with no account if you want none: guest mode keeps the ledger on your device, and signing in later migrates it. No ads, no card, no set behind a gate.

It can be free because the expensive parts are bounded. Hosting is Cloudflare Pages, the database is one small record per account, and the AI functions sit behind daily quotas and de-duplication, so a repeated upload never pays twice.

Three things are different. Lifts, food and bodyweight are one history with one export, not three apps with three subscriptions. The numbers cannot lie by construction: calories are always the sum of the macros, a PR is always a real set beating a real set, an AI estimate always says it is an estimate, and the offline fallback says it is offline. And nothing changes your plan without telling you: a bad-sleep check-in trims today and says so, a deload is never cut, a finished week is frozen forever.

What it is not, yet: in the App Store or on Google Play (the native builds exist and update themselves; store submission is next), an importer for other apps' workout history, or a social network. It keeps the receipts. That is the job.