Documentation

Before you start · Getting started · Hook events · States and effects · Lighting profiles · Troubleshooting · Last updated 26 September 2026

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. LAN devices are driven straight from your machine and their keys never leave it; your account, settings, device list, usage counts and session states sync through our servers. Your prompts, code and session transcripts are never collected. (privacy policy)

Before you start

Price: GBP 2.99/month after a 3-day free trial, with a card required at checkout. Cancel any time from your account; cancel before the trial ends and you pay nothing. Pricing · start the trial.
Computer: Windows, macOS or Linux, with Claude Code or Codex already installed on the same machine. AC Bridge uses the agent you already run, so there is no API key to buy.
Installers download from your account after you sign in; the app needs an active trial or plan to run.
Headless: npm i -g acbridge (Node 22 or newer) from npm; same plan.

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 the headless CLI installs from npm.
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 (see hook events), 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 installs from npm with npm i -g acbridge (Node 22 or newer), and is also bundled inside the desktop app, so a machine with the app already has it. It drives sign-in, the bridge, devices and profiles on a machine with no screen:

Command	What it does
`acbridge setup`	Wires the agent hooks that report session state (see hook events). Once per machine.
`acbridge login`	Browser sign-in; this machine gets its own credential. `--no-browser` prints the URL for a headless box.
`acbridge start` / `stop`	Start and stop the bridge. Stopping reverts every device it touched.
`acbridge status`	Relay, machine, hub and plan. Exits 0 when the bridge is running, so scripts can gate on it.
`acbridge scan`	Finds devices on your LAN. Needs the bridge running.
`acbridge connect <id>`	Claims a scanned device by MAC, IP or discovered id.
`acbridge link <provider>`	Links an account-based provider: Home Assistant, Hue, SmartThings, Tuya, Meross, eWeLink, Govee or MQTT.
`acbridge devices`	List the device graph, or control one: `on`, `off`, `set`, `set-main`.
`acbridge profiles`	Create, edit and bind profiles. `create --starter --bind` wires a scene set to the current folder.
`acbridge groups`	Device groups, shared with the app.
`acbridge integrations`	Linked provider accounts: list, pause, resume, remove.
`acbridge repos`	The folders your agent sessions launch from.
`acbridge doctor`	Checks every requirement and prints the fix for each one.
`acbridge uninstall`	Unwires this machine before `npm uninstall -g acbridge`. `--purge` deletes all local data.

Order for a fresh machine: setup and login in either order, then start, then scan and link, then profiles. Scan and connect talk to the running bridge, which is why it starts first. Add --json to almost any command to script it.

Hook events AC Bridge uses

AC Bridge reads each session's state through the agent's own hook system, exactly as the Claude Code hooks reference and the Codex hooks docs describe it; nothing is scraped from your terminal. acbridge setup, or the app's first-run setup, wires both agents.

Claude Code

Setup installs the AC Bridge plugin into Claude Code, and the plugin registers its own hooks. These are the events it listens to, and the state each one reports:

SessionStart — started, or resumed.
SessionEnd — ended.
UserPromptSubmit — working.
PreToolUse — needs your input when Claude asks you a question (AskUserQuestion), plan ready when it presents a plan (ExitPlanMode), and workflow started.
PostToolUse — keeps the context reading fresh during a long turn, and marks the session working again once you answer a question.
PostToolUseFailure — error.
Notification — by type. permission_prompt is needs permission: Claude Code sends it once a permission prompt has waited about six seconds, so on Claude Code the permission light comes about six seconds after the prompt opens. idle_prompt is idle, about a minute after Claude finished responding if you have not typed since. agent_needs_input is needs your input. Rate-limit warnings and MCP server errors map to rate limited and error.
Stop — finished, at the end of every turn.
StopFailure — error, or rate limited when the provider throttled the turn.
SubagentStart — subagent started.
SubagentStop — subagent finished.
PreCompact — compacting.
PostCompact — compaction done.
PermissionDenied — permission denied.
TaskCompleted — task completed.

The plugin does not use Claude Code's PermissionRequest hook, which fires as the dialog appears; that is why the permission light waits for permission_prompt. Context low and critical, permission-mode and model changes have no hook of their own: the bridge works them out from the session. Setup's own edits to ~/.claude/settings.json are a statusLine entry (it chains any status line you already have, and feeds the context and usage readings behind the threshold states) and a narrow permissions allow-list, so Claude is not asked every time it uses the bridge's own device tools; the hooks live in the plugin, not in that file.

Codex

Setup adds AC Bridge's entries to ~/.codex/hooks.json and keeps any hooks of your own that are already there. It registers:

SessionStart — started, or resumed.
SessionEnd — ended.
UserPromptSubmit — working.
PermissionRequest — needs permission, the moment Codex asks for approval.
PostToolUse — keeps the context reading fresh.
PreCompact — compacting.
PostCompact — compaction done.
SubagentStart — subagent started.
SubagentStop — subagent finished.
Stop — finished.

Codex runs a new hook only after you trust it. After setup, start Codex, type /hooks and trust the AC Bridge hooks; do it again after an update that adds an event, or that event stays silent. acbridge doctor tells you which ones still need trusting. AC Bridge does not use Codex's notify setting, so a notify program you already have keeps working.

States and effects

A profile rule has two halves: the state that triggers it, and the effect your device runs. Both are listed below.

Session states

Thirty states exist in the catalog. Claude Code can emit twenty-nine of them and Codex twenty-four, so the app only offers you the ones the agent you bound can actually produce — the two report different things. The twelve most-used are shown first in the editor; the rest fold under Advanced states. For an example colour on each of the six most-used states, and the Claude Code or Codex hook that sets it off, see the Claude Code status light page.

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. On Claude Code it arrives about six seconds after the prompt opens; on Codex, as soon as Codex asks.
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. On Claude Code, about a minute after it finished responding, if you have not typed since.
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.
sandbox escalation	Codex asked to step outside its sandbox. Codex only — Claude Code never fires it.

Effects

Nine effects, plus plain colour, brightness and on/off. A device advertises which ones it can do; the editor only offers you those, and one-tap presets (Alert, Police, Party, Candle, Sunrise, Breathe) are filtered the same way. Breathe and Candle need no colour, so they work on a plain white bulb.

Effect	What it does
Flash	A set number of on/off blinks, with the on and off time you choose.
Strobe	Rapid blinking at a set rate, for a set duration.
Pulse	Smooth breathing between a low and a high brightness. Needs no colour.
Fade	A glide from one colour to another over a duration — seconds, or a five-minute sunrise.
Loop	Cycles a list of colours, holding and cross-fading each one.
Candle	A warm, irregular flicker at a colour temperature you pick. Needs no colour.
Rainbow	Sweeps the full hue circle.
Siren	Alternates two colours at a set rate.
Meter	Maps a live value onto colour stops — context remaining, for instance, going green to amber to red as it runs down. It keeps tracking rather than playing once.

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

Codex sessions do not change the lights Codex skips a hook until you trust it. Type /hooks inside Codex and trust the AC Bridge hooks, then start a new session; acbridge doctor lists any still waiting.

Still stuck? Email support@ac-bridge.com — a person reads it. Include what you tried and what acbridge doctor printed; that is usually enough to answer in one reply.

Guides

Claude Code status light — which colour means which agent state, the hooks behind each one, supported brands and DIY alternatives.
Claude Code notifications — every free way to know when Claude Code or Codex is done or waiting, and when each one fires.