Documentation

Getting started · Effects reference · Lighting profiles · Troubleshooting

In one paragraph AC Bridge watches the coding agents you already run — Claude Code and Codex — and turns what they are doing into light. A profile maps session states (working, needs permission, finished…) to what your devices should do. You bind a profile to a project folder; from then on, that project's sessions drive those devices. Everything runs on your own machine and your own network.

Getting started

Five steps, roughly ten minutes, most of it waiting for an installer.

Install the app. Sign in here, open your account and download the build for your operating system from the Download tab. Windows, macOS and Linux are all supported, and WSL2 is a first-class target.
Sign in and finish first-run setup. The app checks that Claude Code or Codex is installed, installs the small plugin that reports session state, and offers to open the firewall port device discovery needs. You can re-run any of it later.
Add your devices. Scan finds what is on your network — lights, plugs and LED strips from the usual brands. Integrations is for anything that needs an account or a key: Home Assistant, Hue, SmartThings, Tuya, Meross, eWeLink, Govee, or an MQTT broker.
Make a profile. Pick the states you care about and what each one should do. Start with three: working, needs permission, finished.
Bind it to a project and press Start. Open Claude Code or Codex in that folder as you normally would. Your lights follow the session.

Terminal instead Everything above has a terminal equivalent — the acbridge command ships inside the desktop app and can drive sign-in, the bridge, devices and profiles on a machine with no screen. acbridge doctor checks every requirement and prints the fix for each one.

Effects reference

These are the session states a profile can react to. Not every agent produces every state — Claude Code and Codex report different things, and the app only offers you the ones the agent you bound can actually emit.

State	When it fires
started / resumed	A session begins, or picks up an earlier one.
working	The agent is actively doing something.
needs permission	It is waiting for you to approve an action. The one most people light in red.
needs your input	It asked a question and is waiting on the answer.
plan ready	A plan has been produced and wants review.
idle	Nothing has happened for a while.
finished / task completed	The turn, or the task, is done.
ended	The session closed.
error	Something failed.
permission denied	An action was refused.
context low / context critical	The session is running out of context window.
compacting / compaction done	The context is being compacted, and has finished.
rate limited	The agent's provider is throttling.
usage high / cost high	Your configured usage or spend threshold was crossed.
long run	A session has been going longer than your threshold.
subagent started / subagent finished	A sub-task was spawned, or completed.
plan mode / auto-accept mode / bypass permissions / normal mode	The permission mode changed.
model changed	The session switched model.
review changed	A code review's state changed.
workflow started	A multi-agent workflow began.

Lighting profiles

A profile is a named set of rules: state → what these devices do. Colour, brightness, on/off, or a scene you already have on the device.

Profiles follow your account; devices stay on the machine. A profile you make on one computer appears on the others. The devices and credentials it refers to do not — those are local to the machine that can actually reach them, which is why a profile can show as partly unavailable somewhere else.
One profile per project, per agent. A folder can have one Claude profile and one Codex profile side by side.
Stopping puts things back. Every device the bridge touches is snapshotted before it changes anything, and restored when you stop. Your lights do not stay stuck on "working" purple because you closed a laptop lid.
Quiet hours and thresholds live on the profile: a window where nothing fires, and the usage/duration limits that trigger the "high" states above.

The bridge will not start

In order, because each one rules out the next:

Is your subscription active? Local device control needs an active plan or trial. Check your account; a lapsed subscription pauses automation rather than deleting anything.
Is this machine signed in? Sign in from the app, or run acbridge login.
Has the account finished first-run setup? It is a one-time, per-account step. Finish it in the app, or run acbridge login --if-needed on the machine to complete it from the terminal.
Is something else on the port? The bridge serves a local control API on 127.0.0.1. If a previous copy is still running, stop it (acbridge stop) and start again.
Run the doctor. acbridge doctor checks the agent install, the plugin, the local API, the firewall rule and your account, and prints the fix beside each failure.

Devices found but not controllable Most brands need either a local key or an account link before they will take commands. Open Integrations and link the provider; then re-run Scan and the device moves from "found" to "ready to connect".

Still stuck? Email [email protected] — a person reads it. Include what you tried and what acbridge doctor printed; that is usually enough to answer in one reply.