# 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](https://andon-docs.pages.dev/contributing/setup.md) lists every tool, and which work needs it.

```sh
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`.

```sh
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:

```sh
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](https://andon-docs.pages.dev/contributing/schema-changes.md)). 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](https://andon-docs.pages.dev/contributing/testing.md) says what each suite needs.
