Agent Andon Light

A physical desktop status light and vibe coding companion for Claude Code / CLI coding agents — so you can walk away while an agent works and still know its state at a glance, instead of staring at a terminal.

	Color	Meaning
🟩	Green	Agent working
🟨	Yellow	Waiting on you (permission or input)
🟥	Red	Idle / stopped / session ended
🟩💫	Flashing green	Compacting (internal maintenance, still alive)
🟥〜	Slow pulsing red	Stale / disconnected (device hasn't heard from the host in 30 min)

This doc covers "I already have the hardware, how do I get it running." Building the hardware from scratch starts at device/docs/USER-GUIDE.md.

What You Need

• The assembled device — a Waveshare RP2040-Zero hand-soldered onto the custom PCB, pre-flashed with firmware. Building one from scratch instead? Start at device/docs/USER-GUIDE.md, not here.
• A data-capable USB-C cable.
• Python 3 — Linux only. Windows doesn't need it; the installer is self-contained.

Quick Start

1. Plug in the device with a data-capable USB-C cable.

2. Install the host CLI.

OS	How
Linux	pipx install andon-light — see packaging/linux/README.md
Windows	Download andon-light-setup.exe from Releases and run it — see packaging/windows/README.md

Confirm it can see the device:

andon-light doctor

3. Wire up hooks for your agent:

andon-light install-hooks                 # Claude Code (default)
andon-light install-hooks --agent codex   # Codex CLI

Shows you the exact hook config before touching anything, then merges it into the agent's config file (~/.claude/settings.json for Claude Code, ~/.codex/hooks.json for Codex CLI — or a single project's config for either) once you confirm. Both agents drive the same host CLI and firmware — this is a host-only difference, nothing to reflash. Rationale for each hook mapping: hooks/claude/README.md (Claude Code), hooks/codex/README.md (Codex CLI).

4. Restart your agent (or start a new session) — hook config changes don't apply to a session already running. For Codex CLI specifically, also run /hooks inside it once to trust the new hooks — see hooks/codex/README.md.

From here the light tracks your session automatically — no manual commands needed day to day.

Manual Control

Useful for testing, or to set the light by hand:

Command	Effect
andon-light set working	🟩 Solid green
andon-light set waiting	🟨 Solid yellow
andon-light set idle	🟥 Solid red
andon-light set compacting	🟩💫 Chase-fill (compacting)
andon-light heartbeat	Keepalive, no color change
andon-light doctor	Detect the device and report its port

Troubleshooting

See device/docs/TROUBLESHOOTING.md for the full diagnostic playbook, covering both Windows and Linux.

Documentation

Building & Hardware

• User Guide — build guide: soldering, wiring, glossary
• Bill of Materials — parts list
• Firmware — firmware setup & wire protocol

Software

• Host CLI — CLI development & usage
• Claude Code Hooks — hook mapping & rationale
• Codex CLI Hooks — hook mapping & rationale

Installing

• Linux Install
• Windows Install

Troubleshooting

• Diagnostic Playbook — Windows + Linux

Archive

• 3-Bulb MVP — earlier hardware iteration, not part of the current build

Project Structure

agent-andon-light/
├── device/                 the only ongoing hardware line
│   ├── firmware/            Arduino sketch (C++) — drives the LED strip
│   ├── hardware/             KiCad schematic, PCB, manufacturing files
│   └── docs/                  BOM, user guide, troubleshooting, images
├── host/                   Python CLI (`andon-light`) — talks to the firmware over USB serial
├── hooks/                  Agent hook configs that drive the CLI automatically
│   ├── claude/                Claude Code hooks (settings.snippet.json + README)
│   └── codex/                 Codex CLI hooks (hooks.json + README)
├── packaging/              OS-specific install/build tooling
│   ├── linux/                docs-only install path (pipx, no build step)
│   └── windows/               PyInstaller build + Inno Setup installer
├── scripts/                misc dev/demo scripts
└── archive/                retired hardware iterations, frozen history
    └── led-bulb-mvp/          3-discrete-bulb MVP, superseded by the strip

Status

5 units built and tested — custom PCB, 3D-printed enclosure, firmware, host CLI, and Claude Code hooks all confirmed working end to end. Codex CLI hook support added on top (host-only — no firmware or hardware change involved). Published on PyPI; a one-click Windows installer is available.