Local development
Run Andon from a clone to change it: the server and the board with hot reload, a seeded demo org, and a machine that
runs cards against fake coding agents. You need Node 22 and pnpm 10, and no Supabase: every dev command and test suite
runs on this worktree’s own Postgres (pnpm db:local, started for you). Docker is needed only for the container
checks. Set up from zero lists every tool, and which work needs it.
git clone https://github.com/psci-labs/andon && cd andonpnpm installThe server and the board: pnpm dev
pnpm dev runs this checkout’s own Postgres (in .andon/), the server and the board on one origin,
http://localhost:5173 or the next free port. The first run seeds the demo org and writes its logins to .env.local.
pnpm dev # board + server + Postgres; no machinepnpm dev --seed # the same, with the demo org seeded again into a fresh databasepnpm dev --agent # …and "Dev machine": the real agent against fake orca, claude, gh and codexpnpm dev --agent --real # …with this computer's real claude, codex, gh, orca and tmux (spends real tokens)--agent builds @andon/agent and runs it as a child of pnpm dev. Its log lines start with [agent], Ctrl-C stops
it with everything else, and its tmux socket is andon-dev-<port>. It enrols in the demo org with a clone for each
seeded team, so pressing Run on the Backlog card “Add a dark mode toggle” runs it on Dev machine.
Its whole home is .andon/agent-fake/ (HOME and ANDON_HOME both), so its config, credentials (a file, never the
keychain) and host id stay in the checkout. The enrolment is kept across restarts. After --seed, or once the machine
is revoked, the old home is moved aside to .andon/agent-fake.old-<time> and it enrols again.
--real keeps your HOME, so Claude’s login works, with ANDON_HOME at .andon/agent-real/. It reports this
computer’s repositories to the dev board and runs real Claude on them.
Ctrl-C stops the server, the board and the agent. Postgres keeps running for the next start; pnpm db:local stop ends
it. DEV_BOARD_PORT=5280 pnpm dev picks another board port.
Developing Andon while using the desktop app
The desktop app owns your real agent: ~/.andon, port 8787, ~/.config/andon and ~/.local/bin/andon, which it
rewrites whenever it starts. Don’t install a second andon for the dev board. Run pnpm dev --agent instead: its
machine lives in the checkout and never reads or writes any of those. To keep the dev board beside your real one, add
it in the desktop app as a second instance (http://localhost:5173) and switch between the two with ⌘1 and ⌘2.
Live review: pnpm dev:demo
Reviews use the running app at 1440, 1024 and 390 wide, not just the code. pnpm dev:demo sets up a demo with fake
data on the server, as pnpm dev runs it:
pnpm dev:demo # → http://127.0.0.1:5190; logins printed and written to .env.demo (git-ignored)pnpm dev:demo --stop # stops what it startedIt uses the worktree’s own Postgres, so it is safe from any worktree and needs no Supabase stack. What it does:
- Starts this worktree’s Postgres (
.andon/pg) if it isn’t running, and makes theandon_demodatabase afresh on every start, migrated.pnpm dev’sandondatabase is left alone. - Starts the server on the next free port after the board’s (
DEMO_API_PORTpicks one) and the board’s Vite dev server on port 5190 (DEMO_BOARD_PORTpicks another), the board proxying/apito the server so both share one origin. Emails go to.dev-demo/mail.log. - Sets up Web Push locally: the server gets a fresh VAPID key pair, and the dev server registers the service worker
(
VITE_DEV_SERVICE_WORKER=on). Settings → You → Turn on for this device then works. - Builds
@andon/shared,@andon/clientand@andon/agent. - Seeds Demo Co with fake data only: an owner and a member (
owner@example.com,member@example.com, with fresh passwords each run), four teams, and cards in every column and run state. It also seeds imports, pull requests, outputs, plans and workstreams in the states a review needs. - Enrols Demo Mac: the real agent from
apps/agent/distagainst the fakeorca,claudeandghinapps/agent/test/fakes, in a temporaryANDON_HOMEandHOME, never your own agent config. Itsopenonly logs, and its tmux server istmux -L andon-demo. It has a clone for every team and starts four live runs: running, waiting on a permission, asking a question, and waiting for a reply. - Enrols Lab server, the same agent in direct mode (no Orca), with one scanned clone. Build box is a third machine, offline, that owns the older history.
Backlog cards marked “Try it” run live: drag one to Ready, or open it and press Run, and watch it go from
running to done. “Add a dark mode toggle” commits, opens a draft PR through the fake gh and lands in Review. The fake
Claude follows [fake:…] directives in a card’s notes; the header of apps/agent/test/fakes/claude.mjs lists them.
Logs are in .dev-demo/server.log, .dev-demo/board.log, .dev-demo/agent.log and .dev-demo/agent-direct.log.
.dev-demo/state.json records what was started. --stop stops both agents, their tmux servers, the board and the
server. The Postgres keeps running, as after pnpm dev; pnpm db:local stop ends it.
The Supabase directory
supabase/ is what is left of the original Supabase backend: config.toml and the auth email templates. The
functions run on the server (apps/server/src/functions), and the schema is not there either: db/migrations is its
only source (Schema changes). No suite, check or dev command needs a Supabase stack or the Supabase
CLI. scripts/bootstrap.ts, which set up a Supabase project, has no schema left to push.
Checks
Run pnpm typecheck, pnpm lint and pnpm test before every push. pnpm test includes the server’s database suites
and Playwright, on this worktree’s own Postgres. Testing says what each suite needs.
