Glance at any screen β iPad, phone, or browser β or get a desktop alert β the moment your AI coding agent is working, needs you, done, or stuck.
English Β· δΈζ Β· ζ₯ζ¬θͺ Β· νκ΅μ΄ Β· EspaΓ±ol Β· Deutsch Β· FranΓ§ais
β‘ Fastest start β three commands and you're watching your agents from your phone, anywhere. The relay only ever handles ciphertext it can't read, so your code stays yours:
npm i -g agent-andon
andon hosted setup https://relay.agentandon.com
andon install claude(then restart your agent Β· just kicking the tires? npx agent-andon serve --demo)
Stand an old iPad on your desk β or open the board on your phone or any browser. Submit a task to Claude Code or OpenAI Codex, then go do something else β one glance tells you whether the agent is working, needs you, done, or stuck. No babysitting the terminal, no forgetting to come back.
It's a lightweight, self-hosted way to monitor several AI coding agents at once and get notified the instant one needs your approval, finishes its turn, or gets blocked β on the board (any device), a desktop banner, or your menu bar. No app, no account, zero dependencies.
All your AI coding agents on one board β whatever needs you floats to the top. Claude Code and Codex on the left, their live status on your phone.
Andon (θ‘η―) is the lean-manufacturing signal board: a light that tells the whole floor, at a glance, whether a line is running or needs a human. Same idea, for your agents.
- Zero runtime dependencies β pure Node.js standard library.
- One command to wire up β
andon install claudeedits your hooks for you (with a backup). - Multi-agent native β one full-width row per session; whatever needs you floats to the top.
- Speaks your language β English Β· δΈζ Β· ζ₯ζ¬θͺ Β· νκ΅μ΄ Β· EspaΓ±ol Β· Deutsch Β· FranΓ§ais, auto-detected.
- Any screen β iPad, phone, or browser; no app, no account, no hardware.
Agent Andon installs the native lifecycle hooks for Claude Code and OpenAI Codex and turns each turn into a glanceable signal β on the board (any screen), a desktop banner, or phone push β so you stop watching the terminal waiting for a prompt.
Run many sessions in parallel and see one row per agent; whatever needs you floats to the top. Run a whole fleet and only look when one actually needs you.
Pure Node standard library, zero runtime dependencies, no account, no telemetry β it runs on your machine. An optional content-blind relay (it stores only ciphertext it can't decrypt) adds board-from-anywhere and phone push without exposing your code.
New here? Install β Quickstart β Which setup do you need?. Then, for depth:
| Guide | What's in it |
|---|---|
| Commands & event mapping | full CLI Β· Claude/Codex eventβstate Β· background-task counts Β· naming tiles |
| Notifications | desktop alerts Β· menu bar Β· tuning approvals |
| Running it | start / check / stop the board, Tailscale Serve, the relay |
| Configuration & security | env vars Β· token auth Β· network model |
| Hosted board Β· Deploying a relay | the "board from anywhere" relay β use it, or run one |
| Troubleshooting & FAQ Β· Developing | when something's off Β· contributing |
Claude Code / Codex ββ(native hook)βββΆ andon server (your computer) βββ(SSE push)ββ iPad / phone / browser
- Detect β each tool's native hook mechanism reports state changes. No change to your workflow.
- Relay β a tiny HTTP server on your computer receives the events.
- Display β the board holds an open SSE stream, so a state change shows in well under a second (it falls back to 1 s polling). A signal bar across the top is the "tower light," readable across the room.
State priority (the top bar and the row order take the most urgent one):
stuck (red) > needs-you (amber) > done (green) > working (blue) > idle.
The board: one full-width row per process; stuck / needs-you grow large, show their full message,
and float to the top (auto-scrolled into view), while working / ready / idle stay compact. Calm by default β
only the single most-urgent row pulses. One language per screen, auto-detected (override with the header
dropdown or ?lang=).
npm install -g agent-andon # or: npx agent-andon serve --demoFrom source:
git clone https://github.com/tianshanghong/agent-andon && cd agent-andon
npm install && npm run build
node dist/cli.js serve --demoRequires Node.js β₯ 18.
1. Verify the board with fake data:
andon serve --demoIt prints a http://<your-ip>:8787 URL. Open it on any phone, tablet, or browser β you should see two
rows cycling colors. Once it looks right, Ctrl-C and run for real:
andon serve2. Open the board (iPad, phone, or any browser, same Wi-Fi as the computer):
- Open the printed URL. It's
http://, nothttps://. - Tap "Enable sound" once to unlock the chime (browsers mute audio until you tap; this is the board's in-browser sound, separate from the default-on desktop alerts). Remembered across reloads.
- On a phone/tablet: Add to Home Screen for a full-screen, address-bar-free board. (On a wall iPad, also set Auto-Lock β Never; the page requests a Wake Lock too.)
3. Wire up your agents:
andon install claude # edits ~/.claude/settings.json (keeps a .andon-backup)
andon install codex # edits ~/.codex/hooks.json (keeps a .andon-backup)
andon doctor # confirm everything's connected; reprints the board URLRestart your Claude Code session and it lights up the board automatically. That's it.
Want the board (and phone push) from anywhere, not just this Wi-Fi? β Which setup do you need?
Run the whole board locally with andon serve (free, desktop alerts, no relay), or host your own relay with andon relay (andon verify <url> checks any relay). β full self-host guide
andon serve already gives you the board + desktop alerts on the computer running it β free, zero
setup, on macOS / Linux / Windows. The part that takes more is push to your phone: a buzz when an
agent needs you, phone locked, you away from the desk. Phone push needs a relay reachable over HTTPS
- "Add to Home Screen" on the phone (required on iPhone/iPad). The easy way is our managed relay β nothing to run, no Tailscale, no HTTPS to set up.
flowchart TD
A(["Watch your AI agents"]) --> B{"Just on this computer?"}
B -->|Yes| S["<b>andon serve</b><br/>board + desktop alerts β done"]
B -->|Phone too| C{"Phone PUSH, or just glance?"}
C -->|Glance| L["<b>andon serve</b> + open http://your-ip:8787<br/>same Wi-Fi, board only β http can't push"]
C -->|Push anywhere| M{"Which relay?"}
M -->|Managed| G["βοΈ <b>Our managed relay</b> β easiest, no server<br/>andon hosted setup relay.agentandon.com"]
M -->|Tailscale| T["<b>tailscale serve</b> + andon serve<br/>self-host, just you"]
M -->|Own relay| R["<b>Deploy a relay</b> (Docker)<br/>self-host: team / your infra"]
| You want⦠| Do this |
|---|---|
| Board + desktop alerts on your computer | andon serve β the default (macOS / Linux / Windows), alerts on |
| Glance at the board on a phone/tablet on the same Wi-Fi | andon serve, open http://<your-ip>:8787 β board only; http can't push |
| π± Phone push β the easy way (no server, no Tailscale) | βοΈ our managed relay: andon hosted setup https://relay.agentandon.com + Add to Home Screen β launching, β watch |
| Phone push, self-hosted β just you | tailscale serve + andon serve + Add to Home Screen |
| Phone push, your own relay (team / your infra) | deploy a relay (Docker) + Add to Home Screen |
Rule of thumb: andon serve gives desktop alerts for free, everywhere. Want them on your phone?
β easiest is our managed relay (nothing to run); or self-host with Tailscale (just you) or your
own relay (a team).
andon serve # run the board (desktop alerts on by default)
andon install claude # wire Claude Code hooks (also: install codex)
andon doctor # health check + the board URL
andon post <state> <agent> # push a status by hand
andon uninstall claude # cleanly remove what Andon addedFull reference β every flag, the Claude/Codex event β state mapping, background-task counting, and naming tiles β is in docs/commands.md.
Desktop alerts are on by default β a banner (and sound for needs-you / stuck) on the computer running
the server, degrading gracefully across macOS / Linux / Windows; there's also a menu-bar summary. Tune it
with --say / --no-notify, or pre-approve safe operations so amber fires less. See
docs/notifications.md.
andon serve # foreground β Ctrl-C to stop
nohup andon serve > /tmp/andon.log 2>&1 & # background (macOS / Linux)
pkill -f "cli.js serve" # stop a background oneFull start / check / stop for the board, Tailscale Serve, and the relay: docs/running.md.
Andon is local-first and free to self-host forever β that stays the default. The optional, opt-in relay gives you the board + phone push from anywhere β use our managed relay (zero setup) or run your own (same open-source code):
andon hosted setup https://relay.agentandon.com # opt in β a key is generated that never leaves your machine
andon relay # β¦or run the content-blind relay yourself
andon verify <relay-url> # check a relay serves the exact open-source codeYour status content (its title, message, and agent name) is end-to-end encrypted on your machine
before it leaves; the relay only ever routes and stores that ciphertext, which it cannot decrypt (it
never receives your key) β so it can't read your prompts, code, titles, or messages. It sees only coarse
metadata: that you're active, roughly when, the high-level state, and your IP. "Verifiable, not just trusted": the served code is open-source +
reproducible and andon verify confirms a relay serves exactly it. Full guides:
using the hosted board Β· deploying a relay.
Don't want to run anything? Our managed relay at
relay.agentandon.comis the zero-setup path β it's launching soon; β star / watch to catch the go-live.
By default the server binds 0.0.0.0 with no auth β fine on trusted home Wi-Fi, not on a
public/untrusted network. Set ANDON_TOKEN for a shared network, and don't port-forward it (use the HTTPS
paths above). The board only exposes high-level status β never code or logs. Details + env vars:
docs/configuration.md.
AGPL-3.0-or-later β Β© 2026 wwang.
Run, self-host, audit, fork, and modify Andon freely. If you run a modified version as a network service, AGPL Β§13 asks you to offer its source to your users; running it unmodified (a wall board talking to your own agents) carries no such obligation. The maintainer also offers Andon under separate commercial terms for a hosted service β see CONTRIBUTING for how that stays possible.
The name "Andon" / "Agent Andon" and the logo are reserved marks of the author β the license covers the code, not the name (see TRADEMARK). Forks must use a different name.