AC Bridge docs: status lights for Claude Code and Codex
AC Bridge, also written acbridge, is a desktop app that
turns Claude Code and Codex session states into colours and effects on your smart lights and
plugs.
It runs on Windows, macOS and Linux.
What AC Bridge does
In one paragraph AC Bridge shows what Claude Code and Codex are doing on the lights you already own, so a glance at the room tells you when an agent needs you. A profile maps session states to what your devices do. Bind one to a project folder and its 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)
- Price: £2.99 a month after a 7-day free trial. Add a card to start the trial; nothing is charged for 7 days, and you pay nothing if you cancel before then. Cancel any time from your account. Pricing · start the trial.
- Computer: Windows, macOS or Linux, with Claude Code or Codex installed on the same machine. AC Bridge works through the agent you already run, so there is no API key to buy.
- Installers are in your account after sign-in; the app needs an active trial or plan.
Getting started
Want screenshots? How to set up AC Bridge, step by step walks through each step below in the app.
-
Install the app.
Sign in, open your account and get your build from the Download tab: Windows 10 or 11 (64-bit), macOS (Apple silicon or Intel) or Linux (x64 .deb, .rpm or AppImage).
-
Finish first-run setup.
Sign in. The Set up AC Bridge on this machine screen checks for Claude Code or Codex; press Approve & set up to install the plugin that reports session state (see hook events). You can re-run setup later.
-
Start the bridge.
Press Start in the top bar. From then on the bridge starts by itself when the app opens. AC Bridge runs on one computer at a time; the last one you start takes over.
-
Add your devices.
Scan finds the lights, plugs and LED strips on your network from 16 brands, and offers to open the firewall port device discovery needs. Integrations links the rest: Home Assistant, a Hue Bridge (press its link button), SmartThings, Matter (a pairing code from the app that already controls the device, such as Google Home, Apple Home or SmartThings), Meross and eWeLink (one sign-in fetches the device keys), Tuya (a free Tuya developer key, about 5 minutes once), an MQTT broker, and a Govee API key for Govee plugs and appliances.
-
Make a profile.
On Profiles, press Add profile and choose Claude profile or Codex profile. A new profile starts blank: press + Device to add the lights it drives, then pick the states you care about and choose what each one does. Start with three: working, needs permission, finished.
-
Bind it to a project folder.
On Bridges, press New and add the folder, open its row and, under Agents and lights, pick the profile for Claude or Codex. Then open Claude Code or Codex there as usual. Your lights follow the session.
First launch
-
macOS
The Mac app is signed and notarized by Apple.
Pick the dmg that matches your Mac (Apple menu → About This Mac shows Apple silicon or Intel), open it and drag AC Bridge to Applications. Open it from Applications, not from the dmg.
The first time you open it, your Mac says AC Bridge is an app downloaded from the internet and asks if you are sure. Choose Open. AC Bridge then opens, and your Mac does not ask again for this copy.
-
Linux
.deb, .rpm or AppImage
A system that installs .deb packages: install the .deb with apt. Neither package needs FUSE.
.deb
sudo apt install ./ac-bridge-<version>-linux-amd64.debA system that installs .rpm packages: import the release key once, then install the .rpm. The commands below use
dnf; on a system without it, install the file with its own package tool, or use the AppImage below..rpm
sudo rpm --import https://www.ac-bridge.com/ac-bridge-release-key.asc sudo dnf install ./ac-bridge-<version>-linux-x86_64.rpmUse the exact file name you downloaded; a glob picks up older copies in the folder. To check a file, save its .asc from the Download tab beside it and run
gpg --verify FILE.asc FILE(aftergpg --importof the key), orrpm -K FILE. The release key fingerprint is18B8 6654 1097 056E 68D8 4551 B174 2018 F828 B5F1.Or use the AppImage. Make it executable (
chmod +x) before you double-click it: on Fedora a double-click on a non-executable file opens GNOME Disks. Then install FUSE 2:Ubuntu 24.04 and newer
sudo apt install libfuse2t64libfuse2before that;sudo dnf install fuse fuse-libson Fedora. Without it the AppImage exits with no window and no error. -
Windows
SmartScreen
A new installer carries no SmartScreen reputation yet, so Windows may show “Windows protected your PC”. Choose More info, then Run anyway. The reputation builds as more people download each version.
-
Every platform
“Update required”
Your version is below the minimum supported one, so devices stay paused until the machine updates. Choose Get the update, run the new installer from the Download tab of your account and reopen the app. On a Mac, signed in, the button may read Install update instead: choose it and AC Bridge installs the update and restarts.
macOS
Updating on a Mac
In the app, choose Account & System settings from the account menu, open System and, beside App version, press Check for updates, then Install update: AC Bridge restarts on the new version. To update by hand instead:
- Quit AC Bridge before you replace it. If its icon is in the menu bar, click it and choose Quit AC Bridge. Closing the window is not always enough. If the app is still open, replacing it fails with “The operation can't be completed because the item AC Bridge is in use”.
- Download the new dmg from the Download tab of your account, open it and drag AC Bridge to Applications. If your Mac says an older item named “AC Bridge” already exists, choose Replace.
- Open AC Bridge from Applications. If your Mac says it is an app downloaded from the internet, choose Open.
- Your Mac may also ask for your login password for a Keychain item named AC Bridge Safe Storage. Enter it and choose Always Allow.
Hook events AC Bridge uses
AC Bridge reads each session's state through the agent's own hook system (the Claude Code hooks reference, the Codex hooks docs), and the app's first-run setup wires both agents. Nothing is scraped from your terminal.
Claude Code
Setup installs the AC Bridge plugin, and the plugin registers its own hooks.
| Claude Code event | State |
|---|---|
SessionStart | started, or resumed. |
SessionEnd | ended. |
UserPromptSubmit | working. |
PreToolUse | needs input (AskUserQuestion), plan ready (ExitPlanMode), workflow started. |
PostToolUse | keeps the context reading fresh; working again once you answer. |
PostToolUseFailure | error. |
Notification | by type: permission_prompt is needs permission, agent_needs_input or elicitation_dialog needs input, agent_completed task completed, idle_prompt idle, rate_limit_warning rate limited and mcp_server_error error. Claude Code sends idle about a minute after Claude finished responding, if you have not typed since; AC Bridge usually sets it sooner. |
Stop | finished, at the end of every turn. |
StopFailure | error, or rate limited when the turn ended on a usage limit. |
SubagentStart | subagent started. |
SubagentStop | subagent finished. |
PreCompact | compacting. |
PostCompact | compaction done. |
PermissionDenied | permission denied. |
TaskCompleted | task completed. |
Codex
Setup adds its entries to ~/.codex/hooks.json beside your own hooks, and a marked AC Bridge block to ~/.codex/config.toml for the device tools. Codex runs a new hook
only once trusted: after setup, or an update that adds an event, type /hooks and trust the
AC Bridge hooks, or that event stays silent. Your notify setting is left alone.
| Codex event | State |
|---|---|
SessionStart | started, or resumed. |
SessionEnd | ended. |
UserPromptSubmit | working. |
PermissionRequest | needs permission, the moment Codex asks for approval. |
PostToolUse | keeps the context reading fresh; error when a tool result comes back as an error. |
PreCompact | compacting. |
PostCompact | compaction done. |
SubagentStart | subagent started. |
SubagentStop | subagent finished. |
Stop | finished. |
Claude Code: what the hooks leave out
The plugin takes needs permission from the permission_prompt notification, not the
PermissionRequest hook. Context, permission-mode and model changes have
no hook; 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
have, and feeds the context and usage readings) and a narrow permissions allow-list for its
device tools; the hooks live in the plugin, not that file.
States and effects
A profile rule pairs the state that triggers it with the effect your device runs. A Claude Code profile offers 29 states and a Codex profile 19, because the two agents report different things; the editor lists only the states the agent you chose can produce. Twelve main states are listed first (eight on a Codex profile) and the rest fold under Advanced states. The Claude Code status light page gives an example colour and hook for six states.
| Session state | When it fires |
|---|---|
| started / resumed | A session begins, or picks up an earlier one. |
| working | The agent is actively doing something. |
| needs permission | Waiting for your approval. On Codex, as soon as Codex asks. |
| needs input | It asked a question and is waiting for the answer. Claude Code only. |
| plan ready | A plan is ready for your review. Claude Code only. |
| idle | The turn ended and nothing has happened since. Claude Code only: AC Bridge sets it a moment after the turn, unless you type or Claude asks something; Claude Code's own idle notification is a backstop. |
| finished / task completed | The turn, or the task, is done. Task completed is Claude Code only. |
| ended | The session closed. |
| error | Something failed. |
| rate limited | A state for your Claude plan's usage limit (the 5-hour or weekly window). Claude Code profiles list it. |
| Session state | When it fires |
|---|---|
| context low / context critical | The session is running out of context window. |
| compacting / compaction done | The context is being compacted, and has finished. |
| permission denied | Your permission rules blocked a tool call without asking. Claude Code only. |
| usage high / cost alarm | Plan usage or session spend passed your threshold. Claude Code only. |
| long run | Working without a break past your minutes 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 | Your pull request's review state changed (approved, changes requested). Claude Code only. |
| workflow started | A multi-agent workflow began. Claude Code only. |
Effects
Nine effects, plus plain colour, brightness and on/off. The editor offers only what a device advertises, and filters the one-tap presets (Alert, Police, Party, Candle, Sunrise, Breathe) the same way. Breathe and Candle need no colour, so they work on a dimmable white bulb.
| Device | Effects it gets |
|---|---|
| Colour light | All nine. |
| Dimmable white light | Four: Flash, Strobe, Pulse, Candle. |
| Light that cannot dim | Two: Flash, Strobe. |
| Plug | None. |
| Effect | What it does |
|---|---|
| Flash | A set number of on/off blinks, at an on and off time you pick. |
| Strobe | Rapid blinking at a set rate, for a set duration. |
| Pulse | Breathes between low and high brightness. Needs no colour. |
| Fade | A glide between colours, over 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 (context used, plan usage or session cost) onto colour stops and keeps tracking it. |
Lighting profiles
A profile is a named set of rules, state → what these devices do: colour, brightness, on/off, an effect or a scene.
-
Profiles follow your account.
A profile you make on one computer appears on the others. The devices and credentials it refers to stay on the machine that can reach them, so a profile can show as partly unavailable on another computer.
-
Thresholds live on each state.
Context and plan usage percentages, session cost and minutes working decide when those states fire. Defaults: context low 75%, context critical 90%, usage high 80%, cost alarm 5 US dollars, long run 10 minutes.
-
One profile per project, per agent.
A folder can have one Claude profile and one Codex profile side by side. A profile names the devices it drives, so each project can have its own lamp or one lamp can follow several. When two sessions want the same light, the most recent wins by default.
-
Stopping puts things back.
The bridge records a device's state before it first changes it. Stopping the bridge, or quitting the app, puts back only those devices, as closely as each allows. A session ending does not put things back while the app runs the bridge; give the ended state a scene if you want one. A shutdown reverts before exit and a crash at the next start, so a light does not stay stuck on your working colour. This is on by default: Restore devices when the bridge stops, under Account & System settings, System, Device restore.
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 plan pauses automation and deletes nothing.
-
Is this machine signed in?
Sign in from the app.
-
Is first-run setup finished?
It is a one-time step for each account on each computer. Finish it in the app.
-
Is the port in use?
The bridge serves a local control API on 127.0.0.1, port 8790 by default. If another program holds that port, the app says so: close that program and press Start again, or set a different
hubPortin AC Bridge'sconfig.jsonand restart the app. -
Re-check setup.
In the app, open the account menu (your name, top right), choose Account & System settings, then the System tab. Bridge setup has a Run setup button: it runs setup again and lists each step (Agent-state plugin, Codex hooks, Firewall rule, Statusline tee and the rest) with its state, the reason when one fails, and a command to run by hand when a step needs admin rights. After the first run the button reads Re-check setup.
Devices found but not controllable Ten of the 16 LAN brands need no account (newer Kasa models need your TP-Link login, and an encrypted ESPHome node asks for its API key once), though Govee, Yeelight and Roku need local control switched on first. The rest need a one-time step: a sign-in (Tapo, Meross, eWeLink), a free Tuya developer key, or a button press (Hue Bridge, Nanoleaf). Open Integrations and link the provider, then re-run Scan: the device moves from Needs a one-time setup to Ready to add.
Codex does not change the lights
Codex skips a hook until you trust it. Type /hooks inside Codex, trust the AC
Bridge hooks, then start a new session.
Still stuck? Email support@ac-bridge.com — a person reads it. Include what you tried and what the app's Bridge setup shows.
Guides
- How to set up AC Bridge, step by step — screenshots of each step, from first launch to your first project folder.
- Claude Code notifications: when it is done or waiting — how to know when Claude Code has finished or needs you, and what to check when alerts stop.
- Claude notifications: desktop, mobile and web — where Anthropic documents notifications, what is not confirmed for chat replies, and how to turn them off.
- Claude Code notifications on Windows — a toast from PowerShell with no module, how to check it, and what has not been run yet.
- Claude Code notifications in VS Code — which hooks fired in the extension panel and the integrated terminal on a live run, and what the run left out.
- Codex notifications: when it is done or needs approval — the built-in Codex alerts, notify, and the Stop and PermissionRequest hooks.
- Claude Code status light — how to show the agent's state on a smart bulb you already own, with an example colour for each state.
- Claude Code hooks: every event, with examples — where hooks go, every hook event, matchers, exit codes and a working example for each common job.
- Claude Code and Codex notifications side by side — the events each has, and one hook script that alerts you from both.