acbridge 1.1.0 → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +201 -38
- package/dist/acbridge.mjs +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,73 +2,236 @@
|
|
|
2
2
|
|
|
3
3
|
<img src="https://www.ac-bridge.com/brand/ac-bridge-mark-gradient.png" width="96" alt="AC Bridge">
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/acbridge)
|
|
6
|
+
[](https://nodejs.org)
|
|
7
|
+
[](https://ac-bridge.com)
|
|
6
8
|
|
|
7
|
-
|
|
8
|
-
and Profiles — the scenes that react to what your coding agent is doing.
|
|
9
|
+
**Ambient status for Claude Code and Codex — let your smart home tell you, gently.**
|
|
9
10
|
|
|
10
|
-
|
|
11
|
-
|
|
11
|
+
AC Bridge connects your coding agents to the smart-home devices around you. Instead of a jarring
|
|
12
|
+
completion chime or compulsive tab-switching, the room keeps you informed: the desk lamp shifts to
|
|
13
|
+
amber when Claude is waiting on a permission, pulses red on an error, and settles back to warm
|
|
14
|
+
white when the work is done. Turn the terminal sound effects off for good — glance up from another
|
|
15
|
+
screen, or another room, and know exactly where your agent is.
|
|
16
|
+
|
|
17
|
+
Every state is yours to map to any device, colour, brightness, or scene — the options are
|
|
18
|
+
limitless.
|
|
19
|
+
|
|
20
|
+
`acbridge` is the full terminal peer of the [AC Bridge desktop app](https://ac-bridge.com):
|
|
21
|
+
everything below runs headlessly on a box with no GUI.
|
|
12
22
|
|
|
13
23
|
```sh
|
|
14
24
|
npm i -g acbridge
|
|
15
25
|
```
|
|
16
26
|
|
|
17
|
-
##
|
|
27
|
+
## How it works
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
Claude Code / Codex session ──hooks──▶ local bridge ──▶ your lights & devices
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Lightweight hooks (installed once by `acbridge setup`) report what your agent is doing to a small
|
|
34
|
+
local bridge on your PC. **Profiles** map those session states to device scenes, and the bridge
|
|
35
|
+
applies them live. When a session ends — or you run `acbridge stop` — every device it touched is
|
|
36
|
+
put back exactly the way it was found.
|
|
37
|
+
|
|
38
|
+
Nothing needs to change about how you work: once the bridge is up, lights react to **any**
|
|
39
|
+
`claude` or `codex` session launched in a profile-bound project. No flags, no wrappers.
|
|
40
|
+
|
|
41
|
+
## The states your agent can signal
|
|
42
|
+
|
|
43
|
+
Roughly thirty session states for Claude Code and twenty-three for Codex, including:
|
|
44
|
+
|
|
45
|
+
- **needs permission** — a tool call is waiting on your approval
|
|
46
|
+
- **has a question** / **plan ready** — the agent wants your input
|
|
47
|
+
- **working / finished / error / idle**
|
|
48
|
+
- **context low / context critical** — the context window is filling up
|
|
49
|
+
- **usage high / cost high / long-running** — thresholds you set per profile
|
|
50
|
+
- **plan, auto-accept, and bypass permission modes**, **model changed**, **subagents**,
|
|
51
|
+
**compacting**, **rate limited**, and more
|
|
52
|
+
|
|
53
|
+
Run `acbridge profiles states` for the full catalog with hints and threshold ranges. Each state
|
|
54
|
+
takes a colour (fixed, the device's resting "main" look, or a per-session colour), brightness or a
|
|
55
|
+
relative scale, colour temperature, power, hold-or-revert behaviour, effects — plus an action lane
|
|
56
|
+
that can run any device command. Per-profile quiet hours and do-not-disturb are built in.
|
|
57
|
+
|
|
58
|
+
## Requirements
|
|
18
59
|
|
|
19
60
|
- **Node.js 22 or newer.**
|
|
20
61
|
- **An AC Bridge subscription** — sign up (3-day free trial) at <https://ac-bridge.com>.
|
|
21
|
-
- **[Claude Code](https://claude.com/claude-code) or the OpenAI Codex CLI**, if you want Profiles
|
|
22
|
-
react to your sessions. Device control works without either.
|
|
62
|
+
- **[Claude Code](https://claude.com/claude-code) or the OpenAI Codex CLI**, if you want Profiles
|
|
63
|
+
to react to your sessions. Device control works without either.
|
|
23
64
|
|
|
24
|
-
##
|
|
65
|
+
## Quick start
|
|
25
66
|
|
|
26
67
|
```sh
|
|
27
|
-
acbridge login
|
|
28
|
-
acbridge setup
|
|
29
|
-
acbridge start
|
|
68
|
+
acbridge login # sign this machine in (opens your browser)
|
|
69
|
+
acbridge setup # once per machine: installs the agent hooks
|
|
70
|
+
acbridge start # bring the bridge up in the background
|
|
71
|
+
acbridge scan # find devices on your LAN — each row prints its next command
|
|
72
|
+
acbridge profiles create --starter --bind # wire a ready-made scene set to this project
|
|
30
73
|
```
|
|
31
74
|
|
|
32
|
-
Then launch `claude` (or `codex`) in
|
|
33
|
-
every device it touched back the way it found it.
|
|
75
|
+
Then launch `claude` (or `codex`) in the bound project and watch the room react. `acbridge stop`
|
|
76
|
+
puts every device it touched back the way it found it.
|
|
77
|
+
|
|
78
|
+
The `--starter` scene set pre-wires six states: **working** follows each session's own colour,
|
|
79
|
+
**needs permission / plan ready / error / finished** get attention colours, and **idle** dims to
|
|
80
|
+
30% — all reversible, no holds. Tune any of it afterwards:
|
|
81
|
+
|
|
82
|
+
```sh
|
|
83
|
+
acbridge profiles set-state focus needs_permission --device "desk lamp" --color 30,100 --brightness 80
|
|
84
|
+
acbridge profiles set-state focus error --device "desk lamp" --color 0,100
|
|
85
|
+
acbridge profiles set-state focus finished --device "desk lamp" --return main
|
|
86
|
+
```
|
|
34
87
|
|
|
35
88
|
No browser on the box? `acbridge login --no-browser` prints a sign-in URL served on this machine's
|
|
36
89
|
loopback — open it in a browser **on the same machine**, or over SSH forward the port first
|
|
37
|
-
(`ssh -L 8765:127.0.0.1:8765 <box>`) and open it on your laptop. The command keeps waiting either
|
|
90
|
+
(`ssh -L 8765:127.0.0.1:8765 <box>`) and open it on your laptop. The command keeps waiting either
|
|
91
|
+
way.
|
|
92
|
+
|
|
93
|
+
## Connect your devices
|
|
38
94
|
|
|
39
|
-
|
|
95
|
+
Link an ecosystem account, or connect open-protocol devices directly from a LAN scan:
|
|
40
96
|
|
|
41
|
-
| | |
|
|
97
|
+
| Provider | How to connect |
|
|
42
98
|
|---|---|
|
|
43
|
-
|
|
|
44
|
-
| `acbridge
|
|
45
|
-
| `acbridge
|
|
46
|
-
|
|
|
47
|
-
|
|
|
48
|
-
|
|
|
49
|
-
|
|
|
50
|
-
|
|
|
99
|
+
| **Home Assistant** | `acbridge link home-assistant --url http://homeassistant.local:8123 --token <token>` |
|
|
100
|
+
| **Philips Hue** | `acbridge link hue --host <bridge-ip>` — then press the bridge's link button |
|
|
101
|
+
| **MQTT** (Zigbee2MQTT, Tasmota, ESPresense…) | `acbridge link mqtt --host <broker[:port]>` — every Home Assistant Discovery device appears; no vendor account needed |
|
|
102
|
+
| **SmartThings** | `acbridge link smartthings` — browser sign-in |
|
|
103
|
+
| **Tuya / Smart Life** | `acbridge link tuya` — terminal wizard |
|
|
104
|
+
| **Meross** | `acbridge link meross` — terminal wizard |
|
|
105
|
+
| **eWeLink (Sonoff)** | `acbridge link ewelink` — terminal wizard |
|
|
106
|
+
| **Govee** | `acbridge link govee` — API key |
|
|
107
|
+
| **Nanoleaf** | `acbridge scan` → `acbridge connect <device>` while holding the panel's power button |
|
|
108
|
+
| **TP-Link Kasa, WiZ, Yeelight, LIFX, Shelly, ESPHome…** | `acbridge scan` → `acbridge connect <device>` |
|
|
51
109
|
|
|
52
|
-
|
|
110
|
+
Wizard secrets prompt with muted echo and are stored **only on this machine** — in your OS
|
|
111
|
+
keychain where one is available, `0600` files otherwise. Every secret flag has a `--token-file` /
|
|
112
|
+
`--key-file` / `--password-file` twin for CI, which touches neither argv nor the environment.
|
|
53
113
|
|
|
54
|
-
##
|
|
114
|
+
## Command reference
|
|
55
115
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
116
|
+
Run `acbridge --help`, or `acbridge <command> --help`, for every flag.
|
|
117
|
+
|
|
118
|
+
### Run the bridge
|
|
119
|
+
|
|
120
|
+
| Command | What it does |
|
|
121
|
+
|---|---|
|
|
122
|
+
| `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. |
|
|
123
|
+
| `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. |
|
|
124
|
+
| `acbridge restart` | Stop, then start with the same flags. |
|
|
125
|
+
| `acbridge daemon` | The foreground keeper `start` runs detached — useful under a process manager. Self-heals a crashed bridge (capped respawn). |
|
|
126
|
+
| `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. |
|
|
127
|
+
|
|
128
|
+
### Account
|
|
129
|
+
|
|
130
|
+
| Command | What it does |
|
|
131
|
+
|---|---|
|
|
132
|
+
| `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. |
|
|
133
|
+
| `acbridge logout` | Stops the bridge, revokes this machine's credential, and deletes it locally. |
|
|
134
|
+
| `acbridge whoami` | The signed-in account, this machine's node id and label, the relay, and your plan. |
|
|
135
|
+
|
|
136
|
+
### Devices
|
|
137
|
+
|
|
138
|
+
| Command | What it does |
|
|
139
|
+
|---|---|
|
|
140
|
+
| `acbridge devices` | The connected-device graph — name, type, area, reachability — live from the bridge. |
|
|
141
|
+
| `acbridge devices on <device>` / `off <device>` | Power, by name or id (an ambiguous name lists the candidates). |
|
|
142
|
+
| `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. |
|
|
143
|
+
| `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`. |
|
|
144
|
+
| `acbridge rename <device> <new name>` | A durable rename, everywhere — the app, the graph, the CLI. |
|
|
145
|
+
| `acbridge groups` | Device groups, shared with the app: `add`, `rename`, `remove`, `assign <device> <group>`, `unassign`. |
|
|
146
|
+
|
|
147
|
+
```sh
|
|
148
|
+
acbridge devices off "desk lamp"
|
|
149
|
+
acbridge devices set bedroom brightness.setBrightness --param level=35
|
|
150
|
+
acbridge devices set heater thermostat.setSetpoint --param celsius=21
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### Discovery & integrations
|
|
154
|
+
|
|
155
|
+
| Command | What it does |
|
|
156
|
+
|---|---|
|
|
157
|
+
| `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. |
|
|
158
|
+
| `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. |
|
|
159
|
+
| `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. |
|
|
160
|
+
| `acbridge connect --forget <device>` | Undo a connect; `--purge` also deletes any stored credential. `--auto on/off` answers the auto-connect policy. |
|
|
161
|
+
| `acbridge link <provider>` | Link a provider account (table above). |
|
|
162
|
+
| `acbridge unlink <provider>` | Remove a keyed provider's account, its secrets, and its devices. |
|
|
163
|
+
| `acbridge integrations` | Every linked provider account, with the exact link command for anything missing. `enable` / `disable` pause an account; `remove` deletes one. |
|
|
164
|
+
|
|
165
|
+
### Profiles & projects
|
|
166
|
+
|
|
167
|
+
| Command | What it does |
|
|
168
|
+
|---|---|
|
|
169
|
+
| `acbridge profiles` | Your profiles and which project binds to which, across both agent lanes. |
|
|
170
|
+
| `acbridge profiles create` | New profile — a short wizard on a terminal, or fully flag-driven: `--agent claude/codex`, `--devices <list>`, `--starter`, `--bind`. |
|
|
171
|
+
| `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. |
|
|
172
|
+
| `acbridge profiles states` | Every state a profile can react to, per agent, with hints and threshold ranges. |
|
|
173
|
+
| `acbridge profiles show / edit / rename / duplicate / delete` | Inspect or reshape a profile; `edit` is the interactive editor. |
|
|
174
|
+
| `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. |
|
|
175
|
+
| `acbridge repos` | The project list sessions launch from, shared with the app: `add <path>` (`--root` imports every subfolder), `remove`. |
|
|
62
176
|
|
|
63
|
-
|
|
177
|
+
### Machine setup & health
|
|
178
|
+
|
|
179
|
+
| Command | What it does |
|
|
180
|
+
|---|---|
|
|
181
|
+
| `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). |
|
|
182
|
+
| `acbridge doctor` | Diagnoses everything — agent installs, plugin, sign-in, account, LAN-scan capability, bridge reachability — and **each line prints its own fix**. |
|
|
183
|
+
| `acbridge capture on/off/status` | The per-machine session-transcript capture switch. |
|
|
184
|
+
| `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. |
|
|
185
|
+
|
|
186
|
+
### Voice (preview)
|
|
187
|
+
|
|
188
|
+
AC Bridge was built to make coding agents reachable by voice through Amazon Echo devices —
|
|
189
|
+
`acbridge run` launches a voice-connected session. Voice is switched off in current builds while
|
|
190
|
+
the Alexa skill completes publication, so `run` exits with a notice today. Everything else on this
|
|
191
|
+
page works fully without it.
|
|
192
|
+
|
|
193
|
+
## Scripting
|
|
194
|
+
|
|
195
|
+
Every command follows one exit-code contract, and `--json` (on the commands that take it) prints
|
|
196
|
+
exactly one JSON document on stdout with all narration on stderr — pipes stay parseable:
|
|
64
197
|
|
|
65
198
|
```sh
|
|
66
|
-
acbridge
|
|
67
|
-
|
|
199
|
+
acbridge status --json | jq .hub # "running" | "stopped"
|
|
200
|
+
acbridge stop --json | jq .revert # {reverted, failed, skipped}
|
|
68
201
|
```
|
|
69
202
|
|
|
70
|
-
|
|
71
|
-
|
|
203
|
+
| Exit code | Meaning |
|
|
204
|
+
|---|---|
|
|
205
|
+
| `0` | Success. |
|
|
206
|
+
| `1` | Operational failure. |
|
|
207
|
+
| `2` | Usage error. |
|
|
208
|
+
| `3` | Not signed in / setup incomplete — scripts can branch straight to `acbridge login`. |
|
|
209
|
+
| `4` | Update required — this build is below the minimum version; update, don't retry. |
|
|
210
|
+
| `5` | No active subscription — subscribe at <https://ac-bridge.com>, don't retry. |
|
|
211
|
+
|
|
212
|
+
## Configuration
|
|
213
|
+
|
|
214
|
+
Settings resolve **environment variable → `~/.claude-bridge/config.json` → default**:
|
|
215
|
+
|
|
216
|
+
| Setting | Env | config.json | Default |
|
|
217
|
+
|---|---|---|---|
|
|
218
|
+
| Relay URL | `BRIDGE_RELAY_URL` | `relayUrl` | `https://relay.ac-bridge.com` |
|
|
219
|
+
| Bridge port | `BRIDGE_HUB_PORT` | `hubPort` | `8790` |
|
|
220
|
+
| Machine label | `BRIDGE_MACHINE` | `machine` | short hostname |
|
|
221
|
+
| Secrets dir | `BRIDGE_SECRET_DIR` | — | `~/.claude-bridge` |
|
|
222
|
+
| Auto-profiles | `BRIDGE_AUTO_PROFILES` | `autoProfiles` | on |
|
|
223
|
+
| Codex hooks | `BRIDGE_CODEX_HOOKS` | `autoCodexHooks` | on |
|
|
224
|
+
|
|
225
|
+
## Good to know
|
|
226
|
+
|
|
227
|
+
- **Your credentials stay on your machine.** Device and provider secrets are written to your OS
|
|
228
|
+
keychain where one is available, and to `0600` files otherwise — they never leave the machine.
|
|
229
|
+
`acbridge logout` removes them.
|
|
230
|
+
- **Your agent's tool policy is untouched.** AC Bridge installs no permission rules and never
|
|
231
|
+
changes what your agents are allowed to do — it only listens to their state.
|
|
232
|
+
- **Nothing lingers.** The bridge runs only while something is holding it — the app, a daemon, a
|
|
233
|
+
session. Closing them (or `acbridge stop`) releases it, and stop reverts your devices.
|
|
234
|
+
- **Windows, macOS and Linux**, including WSL2 (`doctor` explains that platform's scanning limits).
|
|
72
235
|
|
|
73
236
|
## Help
|
|
74
237
|
|