# PointCast Micro Bridge · experimental macOS edition

A small, inspectable Python bridge from a private PointCast Signal Room to one Codex Micro Agent Key. No installer, background service, third-party Python packages, firmware update, key remapping, or persistent RGB configuration.

**Verification record:** on September 29, 2026, a connected Codex Micro answered this bridge's read-only `device.status` probe over USB, reporting firmware **0.6.2**. A bounded amber/idle test was later accepted by the native HID write API; the physical color change has **not been visually confirmed**. Accepted writes and visible output are separate results. Firmware **0.4.1** uses the protocol documented by FreeMicro. A second primary implementation, [libremicro 0.1.0](https://docs.rs/crate/libremicro/0.1.0), reports visually verified `thstatus` lighting on **0.6.2**, with matching message fields. On 0.6.2 this bridge requires guided visual qualification in your interactive terminal before room signals can control the light. That qualification lasts only for the current process. Do not downgrade firmware to use this experiment. The web room's lightboard and optional computer audio work independently of this bridge.

The included tests use mocked hardware and network calls. No physical light output has been visually verified for this bridge. This is an independent community integration, not a Work Louder or OpenAI product.

## Get started

Requirements: macOS, Python 3.9 or later, a Codex Micro. USB is preferred; Bluetooth framing is implemented from upstream source but has not been tested here. This is not a general Work Louder or Creator Micro driver. Room dry-run mode also works on other operating systems.

1. Download and unzip `pointcast-micro-bridge.zip`, then open Terminal in the extracted folder.
2. Inspect the script, then run the status check. It sends only a read-only status request; it does not change lights or mappings.

```sh
python3 pointcast_micro_bridge.py --probe
```

A successful response includes `transportVerified: true`, the firmware version, and `knownFirmware`. If opening the device is denied, enable **Input Monitoring** for your terminal in macOS System Settings → Privacy & Security, then quit and reopen that terminal. Accessibility permission is not needed by this bridge: it never injects keys. Existing Codex, Input, remappers, or other device apps may interfere.

3. Open or join a room at <https://pointcast-micro-club.mhoydich.workers.dev/signals/>. Copy its room ID and room token. Anyone with the token has room access, including deletion. Keep it out of screenshots, issue reports, shell history, and agent logs.
4. Enter the token without echoing it or placing it in command history:

```sh
printf 'Room token: '
IFS= read -r -s SIGNAL_ROOM_TOKEN
export SIGNAL_ROOM_TOKEN
printf '\n'
python3 pointcast_micro_bridge.py --room YOUR_ROOM_ID
```

The default is **dry-run**: no HID device opens and no physical command is sent. It prints only new signal modes and sequence numbers. Text, senders, room tokens, and request headers are never logged. Old room messages are skipped when the bridge starts. To validate the room once and exit, add `--once`.

5. Explicitly opt into one physical Agent Key. For firmware **0.6.2**, run guided setup in Terminal:

```sh
python3 pointcast_micro_bridge.py --room YOUR_ROOM_ID --lights --qualify-firmware 0.6.2
```

The bridge first validates the room, then checks that the device reports exactly 0.6.2. Watch key index 5 (the sixth Agent Key): it requests steady amber at 20% brightness for 1.5 seconds, then dim-white idle at 4%. Answer **yes** only if you saw both changes. The prompt accepts only the complete word `yes`; `no`, an empty answer, or any other answer stops without enabling room lights. A non-interactive input stream is rejected before any HID device opens. Piping `yes` cannot qualify the device.

After your confirmation, the bridge skips messages received during setup and responds only to new room signals. The confirmation is held in memory for this process and is never saved or uploaded. Restarting requires another guided check. No response to an earlier test is assumed.

For firmware **0.4.1**, use the upstream documented mode:

```sh
python3 pointcast_micro_bridge.py --room YOUR_ROOM_ID --lights
```

Other firmware versions remain blocked. There is no arbitrary force or firmware-override option. Press **Control-C** to stop, including while waiting at the visual confirmation prompt. Then clear the environment variable:

```sh
unset SIGNAL_ROOM_TOKEN
```

## Optional one-shot visual test on firmware 0.6.2

This explicit command changes one physical Agent Key. It is separate from room polling and needs no room token:

```sh
python3 pointcast_micro_bridge.py --test-signal spark --qualify-firmware 0.6.2
```

The bridge verifies the device reports exactly 0.6.2, claims its local process lock, requests **one steady amber signal at 20% brightness on key index 5 for 1.5 seconds**, then requests dim-white bridge idle at 4%. It does not loop or repeat, and does not update firmware, mappings, or saved RGB settings. This one-shot command does not qualify later room sessions. Use the guided `--lights --qualify-firmware 0.6.2` command above to visually qualify one running process. A successful process exit means the requests were sent; a person must confirm the visible amber signal and return to idle. Other device apps can overwrite the indication.

## What a signal does

| Room mode | Requested key color | Brightness |
| --- | --- | --- |
| calm | Teal | 20% |
| spark | Amber | 20% |
| ping | Lilac | 20% |
| celebrate | Lime | 20% |

These are steady colors, not flashing effects. The bridge requests the signal on Agent Key index **5** by default (the sixth agent key). `--slot 0` through `--slot 5` chooses a different single key. It never synchronizes the keyboard backlight or ambient strip. Bursts coalesce to the newest signal. Commands are limited to at most 2.5 per second; room polling defaults to once every three seconds.

After approximately two seconds, or on an orderly stop, the bridge requests **its own dim-white idle** (4%) for that key. It does not read or restore the previous vendor light state. Network stalls can delay idle cleanup by the request timeout. Unplugging, process crashes, or force-killing the process can prevent cleanup. Let Codex reclaim the key or reconnect the device if needed.

A local process lock prevents two copies of this bridge from claiming the device concurrently. It **does not reserve the key against Codex, Input, or other HID writers**. Those apps can overwrite the signal, and this bridge can overwrite their indication for the chosen key. Choose a key you can temporarily spare; stop the bridge when done. It never changes which action that key performs.

## Privacy and network contract

The room lasts seven days unless deleted earlier. Messages come from `GET /api/rooms/ROOM_ID?after=SEQUENCE` with an HTTPS bearer token from `SIGNAL_ROOM_TOKEN`. The first request establishes the latest room cursor and skips existing history. Subsequent requests use the last returned sequence. The bridge reads only sequence and the four allowed signal modes from messages; it makes no posting or deleting calls.

No raw keystrokes, device events, serial numbers, or device-status contents are uploaded. This bridge has no arbitrary RPC input, local HTTP server, auto-start, or firmware flashing path. HTTPS redirects are rejected so the bearer token cannot be forwarded to another origin. `--server` permits another explicit HTTPS origin, or HTTP localhost for development. Stop and restart to recover from a network error, revoked token, rate limit, or expired room.

Computer audio belongs to the web room and must be enabled there. This script does not produce audio and does not claim the Micro has a speaker.

## Inspect and test

```sh
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s . -v
python3 pointcast_micro_bridge.py --help
```

Tests cover exact USB/BLE packet framing, bounded decoder behavior, disallowed command rejection, a one-key lighting payload, firmware refusal, mock IOKit writes, rate limits, relay validation, token-safe errors, cursor handling, guided yes/no and non-TTY behavior, interruption at the confirmation prompt, and cleanup after failure. Verify the extracted files with `shasum -a 256 -c SHA256SUMS.txt`. They never open a physical device.

See `ATTRIBUTION.md` for source provenance and `THIRD_PARTY_LICENSES.txt` for the upstream MIT license. Protocol notes are source-derived; successful transport, accepted writes, and visually confirmed behavior are separate verification states.