acbridge

Ambient status for Claude Code and Codex — let your smart home tell you, gently.

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 — the options are limitless.

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 — every device it touched is put back exactly the way it was found.

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

Roughly thirty session states for Claude Code and twenty-three 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 or newer.
• An AC Bridge subscription — sign up (3-day free trial) at https://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 on your LAN — 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 six states: working follows 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 --token <token> | | Philips Hue | acbridge link hue --host <bridge-ip> — then press the bridge's link button | | MQTT (Zigbee2MQTT, Tasmota, ESPresense…) | 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 — terminal wizard | | Meross | acbridge link meross — terminal wizard | | eWeLink (Sonoff) | acbridge link ewelink — terminal wizard | | Govee | acbridge link govee — API key | | Nanoleaf | acbridge scan → acbridge connect <device> while holding the panel's power button | | TP-Link Kasa, WiZ, Yeelight, LIFX, Shelly, ESPHome… | acbridge scan → acbridge connect <device> |

Wizard secrets prompt with muted echo and are stored only on this machine — in your OS keychain where one is available, 0600 files otherwise. Every secret flag has a --token-file / --key-file / --password-file twin for CI, which touches neither argv nor the environment.

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. | | acbridge devices on <device> / off <device> | Power, by name or id (an ambiguous name lists the candidates). | | acbridge devices set <device> <capability.command> --param k=v | Any device command — brightness, colour, temperature, locks, thermostats. Validated against the device's real capabilities before anything is sent. | | 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 rename <device> <new name> | A durable rename, everywhere — the app, the graph, 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

Discovery & integrations

| Command | What it does | |---|---| | acbridge scan | Find smart devices on your LAN. Each result prints its exact next command — connect for direct devices, link for ecosystem hubs. --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 --forget <device> | Undo a connect; --purge also deletes any stored credential. --auto on/off answers the auto-connect policy. | | acbridge link <provider> | Link a provider account (table above). | | acbridge unlink <provider> | Remove a keyed provider's account, its secrets, and its devices. | | acbridge integrations | Every linked provider account, with the exact link command for anything missing. enable / disable pause an account; remove deletes one. |

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

Machine setup & health

| Command | What it does | |---|---| | acbridge setup | Once per machine: installs the Claude Code plugin and managed settings (merged, never overwritten), and — if Codex is installed — merges AC Bridge's session-state hooks into ~/.codex/hooks.json (every foreign hook preserved). | | acbridge doctor | Diagnoses everything — agent installs, plugin, sign-in, account, LAN-scan capability, bridge reachability — and each line prints its own fix. | | acbridge capture on/off/status | The per-machine session-transcript capture switch. | | acbridge uninstall | The clean exit: unwires everything setup wired, asks about your account data (default: keep), then hands off to npm uninstall -g acbridge. --purge deletes everything AC Bridge stored so a future install starts fresh. |

Voice (preview)

AC Bridge was built to make coding agents reachable by voice through Amazon Echo devices — acbridge run launches a voice-connected session. Voice is switched off in current builds while the Alexa skill completes publication, so run exits with a notice today. Everything else on this page works fully without it.

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. | | 3 | Not signed in / 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://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 |

Good to know

• Your credentials stay on your machine. Device and provider secrets are written to your OS keychain where one is available, and to 0600 files otherwise — they never leave the machine. acbridge logout removes them.
• Your agent's tool policy is untouched. AC Bridge installs no permission rules and never changes what your agents are allowed to do — it only listens to their state.
• 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).

Help

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

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