Skip to content
AndonDocs
GitHub
Change Andon

Local development

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

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.

shell
git clone https://github.com/psci-labs/andon && cd andon
pnpm install

The 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.

shell
pnpm dev # board + server + Postgres; no machine
pnpm dev --seed # the same, with the demo org seeded again into a fresh database
pnpm dev --agent # …and "Dev machine": the real agent against fake orca, claude, gh and codex
pnpm 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:

shell
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 started

It 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 the andon_demo database afresh on every start, migrated. pnpm dev’s andon database is left alone.
  • Starts the server on the next free port after the board’s (DEMO_API_PORT picks one) and the board’s Vite dev server on port 5190 (DEMO_BOARD_PORT picks another), the board proxying /api to 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/client and @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/dist against the fake orca, claude and gh in apps/agent/test/fakes, in a temporary ANDON_HOME and HOME, never your own agent config. Its open only logs, and its tmux server is tmux -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.