Before you start
You need:- A Next.js app using the App Router, on React 19 and Node 24 or later.
- A GitHub repository for the app. The build runs in GitHub Actions.
- Vercel preview deployments from that repository, through Vercel’s GitHub integration. That’s how requesters get a preview of their feature.
- An Anthropic API key. The interviewer and the build agent use Claude.
- A sign-in system. totalmod asks your app who the signed-in user is.
Set up
1
Add totalmod to your app
In your app’s folder, run:It adds these files and never edits your existing ones. If a file already exists, it’s kept unless you pass
--force.If your app uses a
src/ folder, the app files go under src/. These files are licensed MIT-0, so they’re yours to change.Then install the runtime packages:2
Tell totalmod who is asking
Open The
lib/totalmod.ts and make getRequester return the signed-in user, or null for a signed-out visitor:lib/totalmod.ts
id is hashed before it leaves your app. plan and role are optional, and decide who may send requests.The same file sets where requests are stored. Implement RequestStore against a table in your own database before going live. It has five methods: create, get, update, countSince and latestByUser. The demo app has a Drizzle version.The generated
memoryRequestStore() is fine for trying totalmod out, but it loses requests on restart.3
Show the widget
Render the widget once, in your root layout:It renders nothing for users who can’t send requests. To match your brand, set the
app/layout.tsx
--tms-* custom properties (--tms-accent, --tms-bg, --tms-text, …) on .tms-root.Then add two packages to serverExternalPackages. The flag provider must not be bundled:next.config.ts
4
Set up mock data for previews
Every preview runs on mock data, with no way to reach production. Your app has to support this:The demo app’s preview route is a complete example.
- With
TOTALMOD_MODE=mock, use an in-memory database seeded fromseed/mock.ts, neverDATABASE_URL. Fillseed/mock.tswith users shaped like your real ones: one per plan and role, at realistic volumes. - Add a
/totalmod/previewroute that turns the requester’s signed link into a mock session:
app/totalmod/preview/route.ts
5
Set your policy
totalmod.config.yaml is enforced by deterministic checks in CI, not by prompts:Specs and fix requests that touch auth, billing, migrations, admin, secrets or CI are declined.
6
Connect GitHub
Create two secrets first. Any long random string works:A token. Create a fine-grained personal access token for this one repository, with read and write access to Contents, Issues and Pull requests. Issues and PRs are created as you. For a team, a GitHub App with the same permissions is better; the server README shows how.Actions settings. In the repository, under Settings → Secrets and variables → Actions, add:
Webhook. Under Settings → Webhooks → Add webhook:
- Payload URL:
https://<your app>/api/totalmod/webhooks/github - Content type:
application/json - Secret: your
TOTALMOD_WEBHOOK_SECRET - Events: choose individual events, then Pull requests and Deployment statuses
7
Set the environment variables
In your Vercel project, under Settings → Environment Variables. Production and Preview get different values on purpose:
8
Check your setup
VERCEL_TOKEN and VERCEL_PROJECT_ID first (plus VERCEL_TEAM_ID for a team project). It fails if a credential is in Preview, or if TOTALMOD_MODE or TOTALMOD_PREVIEW_SECRET is missing there.Fix anything it reports, then deploy.Try the loop
Sign in to your deployed app as a normal user and click Request a feature:- Request. Describe a feature in a sentence. The interviewer asks up to four questions, then shows a spec to confirm or edit once.
- Build. Confirming files a GitHub issue labelled
totalmod:build, holding only the spec. The build workflow checks the policy and budgets, has Claude Code build it ontotalmod/req-<id>, checks the changed paths, and opens a draft PR with a risk summary. - Preview. Vercel deploys the branch on mock data. The widget shows the requester a private Try it link that only they can open, valid for 24 hours.
- Fix rounds. The requester can ask for changes, up to
iterations.maxtimes. Each one is rewritten into concrete changes before it reaches the build agent. - Approval. Looks good marks the PR ready for your review.
- Release. You review and merge. The feature turns on for the requester first, behind a flag. Add a label to the merged PR to go further:
totalmod:rollout-25for 25% of users (any number from 1 to 99),totalmod:gafor everyone, ortotalmod:offto switch it off. Afterflags.removeAfterDaysat full rollout, a PR removes the flag.
isRequestEnabled(user.id, reqId) from @totalmod/flags. The build agent adds this for you.
Try it without an API key
The interviewer can run on Ollama or LM Studio, so you can try the request flow with a model you already have. From a clone of the totalmod repo:GitHub is stubbed in this demo, and only a model on the same machine is accepted, so this is for testing, not production.
If something doesn’t work
The widget doesn't show
The widget doesn't show
getRequester returned null, or requesters in totalmod.config.yaml excludes this user.The build doesn't start
The build doesn't start
Check that
TOTALMOD_TRUSTED_ACTORS matches the account the issue was filed as, and that budgets aren’t spent. The workflow comments on the issue when it stops.No Try it link
No Try it link
Check the webhook’s events (Pull requests and Deployment statuses) and its secret, and that the preview deployment succeeded.
The preview link says it's not valid
The preview link says it's not valid
TOTALMOD_PREVIEW_SECRET must be the same in Production and Preview.Telemetry and license
totalmod sends anonymous counts, such as requests submitted and previews ready, and never request text, code, prompts or user ids. The CLI says so on first run. Turn it off withDO_NOT_TRACK=1 or telemetry: false.
totalmod is free under the AGPL-3.0, or available under a commercial license for closed-source products. Files that npx totalmod init adds are MIT-0.