acbridge

Status lights and notifications for Claude Code and Codex, on the smart lights you already own.

AC Bridge connects your coding agents to the smart-home devices around you. Instead of a jarring completion chime or compulsive tab-switching, the room keeps you informed: the desk lamp shifts to amber when Claude is waiting on a permission, pulses red on an error, and settles back to warm white when the work is done. Turn the terminal sound effects off for good — glance up from another screen, or another room, and know exactly where your agent is.

Every state is yours to map to any device, colour, brightness, or scene.

acbridge is the full terminal peer of the AC Bridge desktop app: everything below runs headlessly on a box with no GUI.

npm i -g acbridge

How it works

Claude Code / Codex session ──hooks──▶ local bridge ──▶ your lights & devices

Lightweight hooks (installed once by acbridge setup) report what your agent is doing to a small local bridge on your PC. Profiles map those session states to device scenes, and the bridge applies them live. When a session ends — or you run acbridge stop — the devices it changed go back as close to how it found them as each device allows.

Nothing needs to change about how you work: once the bridge is up, lights react to any claude or codex session launched in a profile-bound project. No flags, no wrappers.

The states your agent can signal

29 session states for Claude Code and 19 for Codex, including:

• needs permission — a tool call is waiting on your approval
• has a question / plan ready — the agent wants your input
• working / finished / error / idle
• context low / context critical — the context window is filling up
• usage high / cost high / long-running — thresholds you set per profile
• plan, auto-accept, and bypass permission modes, model changed, subagents, compacting, rate limited, and more

Run acbridge profiles states for the full catalog with hints and threshold ranges. Each state takes a colour (fixed, the device's resting "main" look, or a per-session colour), brightness or a relative scale, colour temperature, power, hold-or-revert behaviour, effects — plus an action lane that can run any device command. Per-profile quiet hours and do-not-disturb are built in.

Requirements

• Node.js 22.13 or newer.
• An AC Bridge subscription — start the 3-day free trial at https://www.ac-bridge.com/.
• Claude Code or the OpenAI Codex CLI, if you want Profiles to react to your sessions. Device control works without either.

Quick start

acbridge login                        # sign this machine in (opens your browser)
acbridge setup                        # once per machine: installs the agent hooks
acbridge start                        # bring the bridge up in the background
acbridge scan                         # find devices you can control — each row prints its next command
acbridge profiles create --starter --bind    # wire a ready-made scene set to this project

Then launch claude (or codex) in the bound project and watch the room react. acbridge stop puts every device it touched back the way it found it.

The --starter scene set pre-wires seven states: started and working follow each session's own colour, needs permission / plan ready / error / finished get attention colours, and idle dims to 30% — all reversible, no holds. Tune any of it afterwards:

acbridge profiles set-state focus needs_permission --device "desk lamp" --color 30,100 --brightness 80
acbridge profiles set-state focus error --device "desk lamp" --color 0,100
acbridge profiles set-state focus finished --device "desk lamp" --return main

No browser on the box? acbridge login --no-browser prints a sign-in URL served on this machine's loopback — open it in a browser on the same machine, or over SSH forward the port first (ssh -L 8765:127.0.0.1:8765 <box>) and open it on your laptop. The command keeps waiting either way.

Connect your devices

Link an ecosystem account, or connect open-protocol devices directly from a LAN scan:

| Provider | How to connect | |---|---| | Home Assistant | acbridge link home-assistant --url http://homeassistant.local:8123 --sign-in — signs in through your browser; nothing to paste, nothing that expires. (--token-file <path> with a long-lived token is the headless route.) | | Philips Hue | acbridge link hue --host <bridge-ip> — then press the bridge's link button (acbridge scan prints the line with the IP filled in) | | MQTT (Zigbee2MQTT, ESPresense, OpenMQTTGateway) | acbridge link mqtt --host <broker[:port]> — every Home Assistant Discovery device appears; no vendor account needed | | SmartThings | acbridge link smartthings — browser sign-in | | Tuya / Smart Life | acbridge link tuya — paste your free Tuya project's Access ID + Secret; the bridge finds the data centre itself (--region overrides). Ends with "Connect the N devices found now? [Y/n]" (--yes to skip the question) | | Meross | acbridge link meross — email + password; no region needed (--region overrides), a 2FA code only if Meross asks (--mfa). Ends with the same connect offer | | eWeLink (Sonoff) | acbridge link ewelink — email + password; no region needed. Ends with the same connect offer | | SONOFF in DIY mode (no account) | acbridge link sonoff-diy --ssid <home-wifi> — hands the device your Wi-Fi from its own setup network; the password is asked for hidden, or comes from --password-file / BRIDGE_WIFI_PASSWORD | | Govee | acbridge link govee — API key. Ends with the same connect offer | | Matter (a device already set up in another Matter app — Google Home, Apple Home, SmartThings and others) | acbridge link matter <code> — the setup code from that app's share / "link to another app" screen; the device stays in that app too, and no account or cloud is involved. When acbridge scan sees the device waiting, it prints the command with --ip filled in | | Nanoleaf | acbridge scan → acbridge connect <device> while holding the panel's power button — it keeps trying for 30 seconds | | TP-Link Tapo | acbridge scan → acbridge connect <device> — if the device refuses, connect shows where to turn on Third-Party Compatibility in the Tapo app, then retries. (Tapo devices on TP-Link's newest TPAP encryption can't be added yet; the scan says so.) | | TP-Link Kasa, WiZ, Yeelight, LIFX, Shelly, ESPHome… | acbridge scan → acbridge connect <device> |

Wizard secrets are typed without being shown on screen and are stored only on this machine — in 0600 files, mirrored into your OS keychain where one is available. Every secret flag has a --token-file / --key-file / --password-file twin for CI, which touches neither argv nor the environment — prefer it (or the environment variable) to --password, which shows in ps and your shell history. Run with no terminal, a wizard never hangs on a prompt: it stops with exit code 2 and names the flags it needs. Moving machines? acbridge backup export writes a passphrase-encrypted bundle of your device credentials, and acbridge backup import merges it safely on the new box.

Command reference

Run acbridge --help, or acbridge <command> --help, for every flag.

Run the bridge

| Command | What it does | |---|---| | acbridge start | Bring the bridge up in the background and return your terminal. Idempotent — a second start reports "already running". --no-revert skips the device restore on stop; --attach runs in the foreground. | | acbridge stop | The complete off-switch: restores every touched device ("lights: reverted 6 of 7 devices"), then tears the bridge down. Running agent sessions are left alone. | | acbridge restart | Stop, then start with the same flags. | | acbridge daemon | The foreground keeper start runs detached — useful under a process manager. Self-heals a crashed bridge (capped respawn). | | acbridge status | Everything at a glance: sign-in, plan, bridge, daemon, devices session. The exit code is the bridge state (0 running, 1 stopped) so scripts can health-gate on it. |

Account

| Command | What it does | |---|---| | acbridge login | Browser sign-in for this machine; also how you switch accounts. --if-needed is the idempotent form for scripts; --provider google/github/microsoft/sso and --email <addr> skip the chooser; --no-browser prints the URL instead. | | acbridge logout | Stops the bridge, revokes this machine's credential, and deletes it locally. | | acbridge whoami | The signed-in account, this machine's node id and label, the relay, and your plan. |

Devices

| Command | What it does | |---|---| | acbridge devices | The connected-device graph — name, type, area, reachability — live from the bridge, under the names the app shows. | | acbridge devices show <device> | One device's capabilities, the commands each takes, and the --instance name for a device with several scenes or channels. | | acbridge devices on <device> / off <device> | Power, by name or id (an ambiguous name lists the candidates). Quote a multi-word name: "desk lamp". | | acbridge devices set <device> <capability.command> --param k=v | Any device command — brightness, colour, temperature, scenes, thermostats. Validated against the device's real capabilities before anything is sent; --instance <name> picks one of several. | | acbridge devices set-main <device> | The device's resting "main" look — what profile scenes return to. --color <hue>,<sat>, --brightness <0-100>, --kelvin <k>, each settable or cleared with none. | | acbridge devices settings <device> | The device's other settings from the app — sharing between sessions, whether Profiles use it, channel names, favourite scenes, a display name. No flags prints them. | | acbridge devices replace <old> <new> | Swapped a bulb? Move every Profile, automation and setting to the new device, name included. Shows the plan and asks; --yes to skip the question. | | acbridge rename <device> <new name> | A durable rename. A network device is renamed everywhere; any other (Hue, cloud, a strip's outlet) gets a display name in the app and the CLI. | | acbridge groups | Device groups, shared with the app: add, rename, remove, assign <device> <group>, unassign. |

acbridge devices off "desk lamp"
acbridge devices set bedroom brightness.setBrightness --param level=35
acbridge devices set heater thermostat.setSetpoint --param celsius=21

Locks, garage doors and other security devices need a person. A command for one asks you y/N at an interactive terminal, naming the device and the action. From a script, with --json, or inside a Claude Code or Codex session, it is refused — never asked — so an agent can't unlock a door through the CLI. Approve it in the app, or run the command yourself and say yes.

Discovery & integrations

| Command | What it does | |---|---| | acbridge scan | Find the smart devices on your LAN that AC Bridge can control, in three groups — Ready to add, Hubs & bridges to link, Needs a one-time setup — each with what it controls and its exact next command (connect for direct devices, link for hubs and brand accounts). Phones, computers, the router and anything else it can't control are left out and counted; --all lists every device it saw, with why each one is hidden. --timeout <s> caps the poll. | | acbridge connect <mac or ip or id> | Onboard one device directly into the bridge. --name sets its display name; --credentials-file <path> supplies credentials headlessly. | | acbridge connect <ip> --as govee/wiz/yeelight/kasa/esphome | Connect-by-IP for a device the scan's fingerprint missed — persists only after a live probe replies. | | acbridge connect <device> --forget | Undo a connect; --purge also deletes any stored credential. Either way, auto-connect never adds that device back — connecting it again yourself does. --auto on/off answers the auto-connect policy; on also adds the eligible devices already found, straight away. | | acbridge link <provider> | Link a provider account (table above). | | acbridge unlink <provider> | Remove a keyed provider's account, its secrets, and its devices — including an account linked by key alone, with no devices on your network. | | acbridge unlink matter <device> | Take one Matter device off AC Bridge (its name or id from acbridge devices). It stays in its other app; if it doesn't answer, you're told to remove AC Bridge there. | | acbridge unlink matter --reset | Reset Matter: AC Bridge leaves every Matter device it can reach and erases its Matter data on this PC — the fix when that data is damaged. Every Matter device must then be shared again. Asks first; --yes skips the question. | | acbridge integrations | Every linked provider account (Matter included), with the exact link command for anything missing. enable / disable pause an account; remove deletes one. | | acbridge integrations exit-plan | Leaving SmartThings? Where each SmartThings device can go instead — connected directly, shared via Matter, or through Home Assistant or MQTT — with the command for each step. |

Profiles & projects

| Command | What it does | |---|---| | acbridge profiles | Your profiles and which project binds to which, across both agent lanes. | | acbridge profiles create | New profile — a short wizard on a terminal, or fully flag-driven: --agent claude/codex, --devices <list>, --starter, --bind. | | acbridge profiles set-state <profile> <state> | The scripting surface for one state's scene: --device, --color, --brightness, --kelvin, --power, --return, --hold, --effect-json, an --action lane, --threshold, --announce, and more. | | acbridge profiles states | Every state a profile can react to, per agent, with hints and threshold ranges. | | acbridge profiles show / edit / rename / duplicate / delete | Inspect or reshape a profile; edit is the interactive editor. | | acbridge profiles bind <profile> / unbind | Attach a profile to a project, per agent lane — Claude and Codex bindings coexist on one repo. --repo defaults to the current folder. | | acbridge repos | The project list sessions launch from, shared with the app: add <path> (--root imports every subfolder), remove. | | acbridge brief / brief on / brief off | Print the device brief a session in this project receives, or switch it on or off — the app's "Make agent aware of devices in chat" tick box. --profile <name> targets a profile directly. |

Machine setup & health

| Command | What it does | |---|---| | acbridge setup | Once per machine: installs the Claude Code plugin (its hooks drive your Profiles) and the statusline feed, pre-approves the bridge's own device tools for your agent, and — if Codex is installed — merges AC Bridge's session-state hooks into ~/.codex/hooks.json (every foreign hook preserved) and registers its device tools. It writes no managed settings. The LAN-scan firewall rule comes last; on Windows the CLI prints the netsh commands to run as administrator. With the desktop app installed, all of this stays bound to the app. | | acbridge doctor | Diagnoses everything — agent installs, plugin, sign-in, account, the files your agent hooks point at, LAN-scan capability, Matter network readiness, bridge reachability — and each line prints its own fix. --json for scripts. | | acbridge backup export / import | A passphrase-encrypted bundle of this machine's device credentials. Export is non-destructive and verified; import asks before touching a credential this machine already holds with a different value (--force in a script) and snapshots it, then merges each device keystore into the one here (the live value wins) and replaces the single-credential stores. In a script, give the passphrase with --passphrase-file <path> or BRIDGE_BACKUP_PASSPHRASE. | | acbridge uninstall | The clean exit: unwires everything setup wired (and tidies the files it created), asks about your account data (default: keep), then hands off to npm uninstall -g acbridge. With the desktop app installed, the app keeps its own wiring. --purge deletes everything AC Bridge stored so a future install starts fresh. |

Scripting

Every command follows one exit-code contract, and --json (on the commands that take it) prints exactly one JSON document on stdout with all narration on stderr — pipes stay parseable:

acbridge status --json | jq .hub        # "running" | "stopped"
acbridge stop --json | jq .revert       # {reverted, failed, skipped}

| Exit code | Meaning | |---|---| | 0 | Success. | | 1 | Operational failure. | | 2 | Usage error — including a command that needs a person or an answer the script can't give (a security device, a wizard with no terminal). | | 3 | Not signed in, a sign-in that is no longer accepted, or setup incomplete — scripts can branch straight to acbridge login. | | 4 | Update required — this build is below the minimum version; update, don't retry. | | 5 | No active subscription — subscribe at https://www.ac-bridge.com/, don't retry. |

Configuration

Settings resolve environment variable → ~/.claude-bridge/config.json → default:

| Setting | Env | config.json | Default | |---|---|---|---| | Relay URL | BRIDGE_RELAY_URL | relayUrl | https://relay.ac-bridge.com | | Bridge port | BRIDGE_HUB_PORT | hubPort | 8790 | | Machine label | BRIDGE_MACHINE | machine | short hostname | | Secrets dir | BRIDGE_SECRET_DIR | — | ~/.claude-bridge | | Auto-profiles | BRIDGE_AUTO_PROFILES | autoProfiles | on | | Codex hooks | BRIDGE_CODEX_HOOKS | autoCodexHooks | on | | Codex device tools | BRIDGE_CODEX_MCP | autoCodexMcp | on | | Agent permissions | BRIDGE_AGENT_PERMS | autoAgentPermissions | on | | Statusline feed | BRIDGE_STATUSLINE | autoStatusline | on |

Good to know

• Your credentials stay on your machine. Device and provider secrets are written to 0600 files, mirrored into your OS keychain where one is available — they never leave the machine. acbridge logout removes them; acbridge backup export is how they move with you.
• Your agent's tool policy is yours. acbridge setup pre-approves only the bridge's own device tools (switch it off with BRIDGE_AGENT_PERMS=0; uninstall removes exactly those entries), and an agent can never work a lock, a garage door or another security device — those need you.
• Nothing lingers. The bridge runs only while something is holding it — the app, a daemon, a session. Closing them (or acbridge stop) releases it, and stop reverts your devices.
• Windows, macOS and Linux, including WSL2 (doctor explains that platform's scanning limits).
• Upgrading: acbridge stop, then npm i -g acbridge@latest. On Windows the install fails while the bridge is running from the package folder.

Help

• acbridge doctor — most problems name their own fix.
• Docs, downloads and account: https://www.ac-bridge.com/ (docs: https://www.ac-bridge.com/docs)
• [email protected]

(c) 2026 AC BRIDGE LIMITED. All rights reserved. Use of this software is governed by the terms at https://www.ac-bridge.com/terms. Works with Claude Code and Codex. Not affiliated with or endorsed by Anthropic or OpenAI.