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. No card is needed to start; add one before the trial ends to keep going, or let it end and pay nothing. 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 app checks for Claude Code or Codex and installs the plugin that reports session state (see hook events). You can re-run setup later.
-
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, Tuya, Meross and eWeLink (a one-time key fetch), an MQTT broker, and a Govee API key for Govee plugs and appliances.
-
Make a profile.
A new profile starts blank. Pick the states you care about and choose what each one does. Start with three: working, needs permission, finished.
-
Bind it and press Start.
Bind the profile to a project folder, press Start and 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.
macOS
Updating on a Mac
- 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 @bridge/app 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 your 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 needs your input, agent_completed task completed and idle_prompt idle. 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. |
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. 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. |
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 your input | It asked a question and is waiting for the answer. Claude Code only. |
| plan ready | A plan is ready for your review. |
| idle | The turn ended and nothing has happened since. On Claude Code, 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. |
| 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. |
| usage high / cost high | 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. |
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, such as context remaining, 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%, 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, or the session ending, puts back only those devices, as closely as each allows. A shutdown reverts before exit and a crash at the next start, so a light does not stay stuck on your working colour.
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, per-account step. Finish it in the app.
-
Is the port in use?
The bridge serves a local control API on 127.0.0.1. If a previous copy of the app is still running, quit it and open the app again.
-
Re-check setup.
In the app, open Account & System, then the System tab. Bridge setup lists each step (the agent plugin, the hooks, the firewall rule and the rest), its state, and a command to run by hand if it fails. Re-check setup runs the checks again.
Devices found but not controllable Ten of the 16 LAN brands need no account or key (newer Kasa models are the exception), though Govee, Yeelight and Roku need local control switched on first. The rest need a one-time step: a sign-in or key fetch (Tapo, Tuya, Meross, eWeLink) or a button press (Hue Bridge, Nanoleaf). Open Integrations and link the provider, then re-run Scan: the device moves from "found" to "ready to connect".
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.