Omni Loop
Omni Loop turns product plans into delivered software across Vertuoza's engineering repositories.
A PM writes a PRD. The PRD becomes a plan of waves and slices, and coding agents deliver it. Anyone with a
coding-agent slot can lend it to a PRD they do not own.
The loop works with Claude Code, Codex, Cursor, Gemini CLI and any coding agent that reads
AGENTS.md: see Any coding agent.
On top of that delivery sits a game. Each PRD is a planet the organisation terraforms together.
Unanswered questions, stuck slices and shipped bugs are Entropy, and they cost the owning team
points until someone closes them. The game only reads the delivery layer and can be removed
without touching it (game/, .github/workflows/game.yml).
Repository layout
A pnpm workspace:
| Path | What |
|---|
kit/ | the delivery kit (omni CLI) |
game/ | the game layer: projector, ledger, economy, banner, rankings |
packages/design | @omni/design: the Omni Loop design system — the colour tokens (tokens.css), the fonts (fonts.css), the 16-bit crest logo, the OMNI_LOOP brand, hand-placed pixel sprites and the planet renderer (README) |
packages/galaxy | @omni/galaxy: folds ledger events into the galaxy view; the demo world |
apps/galaxy | @omni/galaxy-app: the OMNI LOOP arcade, a Next.js app for Vercel |
supabase/ | the game's database and source of truth: migrations, access checks, config, demo seed |
Getting started
Prerequisites
- Node 22 or later, and pnpm
- The GitHub CLI, logged in:
gh auth status
Install and test
pnpm install
pnpm test
The tests run entirely on fixtures and never call GitHub.
Environment variables
The kit, the game and the scripts read their environment once, in kit/lib/env/read.ts, as groups:
each one set whole, or left unset and its feature off. A group half set or a malformed value stops
the command with one line naming the variables, never a value (ADR-0057). Every one is optional:
OPENROUTER_API_KEY, and optionally OPENROUTER_MODEL: the model omni harvest asks where each
decision belongs, and whether a rule is worth a law; omni knowledge judge, the sweep of a
repository's untested laws, needs it (Laws and their tests).PROOF_URL and PROOF_STORAGE_STATE: the address /omni:prove films and the file
omni proof session writes its sign-in to.OMNI_LOOP_WORKSPACE: the workspace a game command plays for when --workspace names none.SUPABASE_URL (or NEXT_PUBLIC_SUPABASE_URL) and SUPABASE_SERVICE_ROLE_KEY: the game's
database, for the game:* commands, personas-import and schemas:verify --production.OMNI_TOKEN: a kit token (omk_…, made by omni setup-token) that signs every omni command in
to the Omni page where no browser can, such as a cloud session; set, it wins over the sign-in
omni signin keeps, and omni whoami prints (OMNI_TOKEN ··<last four>).OMNI_SESSION_ID: the session id every omni command records its work under and
omni dossier open tags a draft with, under any coding agent; set, it wins over the session id
Claude Code sets. Unset under an agent that gives none, omni dossier open generates one
and keeps it for the checkout in .omni-loop/local/session.json.OMNI_HEARTBEAT: off stops the heartbeat every omni command run in a session sends the Omni
page, at most once a minute and in the background; on, or unset, keeps it. Claude Code's own
hook still runs omni heartbeat after each tool call.OMNI_ASK: on turns ask mode on with no omni ask on, as a cloud session's fresh clone needs, so
omni ask question asks the person on the Omni page; off turns it off whatever omni ask on
wrote; unset, omni ask on and omni ask off decide.
The app and the arcade each list their own: apps/omni-app/README.md,
apps/galaxy/README.md.
Open the galaxy
pnpm galaxy:dev # http://localhost:3000 — the arcade, on the demo galaxy
With a local Supabase, Vercel deployment and the artifact build: apps/galaxy/README.md.
Describe your repositories and fleets
Everything the game knows lives in Supabase (apps/galaxy/README.md),
and belongs to a workspace: Vertuoza is the workspace vertuoza. Repositories are grouped into
sectors and the fleets are rows in teams, both of a workspace, and both changed by a
migration in supabase/migrations/:
insert into public.sectors (workspace_id, name, repos)
select id, 'core-belt', array['nimbus-core', 'nimbus-api'] from public.workspaces where slug = 'vertuoza';
insert into public.teams (workspace_id, name, label, color, motto, mascot, home, sort)
select id, 'pirates', 'PIRATES', '#2fc6a4', 'Takes the zones nobody claims.', 'pirate', 'core-belt', 50
from public.workspaces where slug = 'vertuoza';
update public.teams set retired_at = now() -- retire, never delete
where name = 'invincible-team' and workspace_id = (select id from public.workspaces where slug = 'vertuoza');
The fleets today: BEAVER, OCTOPOD, PICSOU, C.I.A. and PIRATES. People join one in the arcade: they
sign in with their GitHub account, which makes them members of the workspace of every GitHub org of
theirs that has the Omni App installed (vertuoza for the vertuoza org), pick a fleet, enter a
name and build a hero, and from then on their pull requests score for that fleet.
Run it by hand
With SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY set (locally: npx supabase status). Each
command reads and writes one workspace, named by --workspace <slug> or, failing that, by
OMNI_LOOP_WORKSPACE; there is no default:
pnpm game:banner 2332 --workspace vertuoza # one planet's banner, read live from GitHub
pnpm game:project --workspace vertuoza # snapshot the workspace's GitHub and append new events to its ledger
pnpm game:score --workspace vertuoza # fold its ledger into this month's season
pnpm game:export backup/ --workspace vertuoza # its row, ledger, sectors, fleets and players as JSONL
game:project writes permanent history. Run it against production only once the sectors hold the
real repositories.
Switch on the scheduled workflow
The workflow polls every 15 minutes and posts rankings every Monday. It does nothing until it is
switched on. The token, rankings issue and GAME_ENABLED steps are described in
game/README.md › Setup.
License
Omni Loop is free software under the GNU Affero General Public License v3.0
(AGPL-3.0-only). You may copy, change and share it; anyone who runs a changed version as a
network service must publish its full source under the same license. The fonts in
packages/design/fonts/ keep their own SIL Open Font License, beside each font.
