Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,8 @@ jobs:
with:
node-version: "24"
# The package has no dependencies and no lockfile, so there is nothing to install.
# The self-check needs no device and no socket: it reports both as absent and exits 0.
# The self-check and the regression suite need no device, no SidePulse and no
# OpenCode. compat.yml runs the tests that do.
- run: npm test

publish:
Expand Down
96 changes: 96 additions & 0 deletions .github/workflows/compat.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
name: compat

# Runs the plugin against real releases of the two programs it sits between. The pinned
# entries are regression tests. The floating ones (SidePulse main, the latest OpenCode)
# also run every week, so a breaking change upstream shows up here first.
#
# None of these jobs gate the npm release. That is the `test` job in ci.yml.

on:
pull_request:
push:
branches: [main]
schedule:
- cron: "17 5 * * 1"
workflow_dispatch:

permissions:
contents: read

jobs:
# OpenCode runs plugins under Bun. ci.yml runs the same suite under Node.
bun:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: oven-sh/setup-bun@v2
- run: bun plugin.mjs
- run: bun test/run.mjs

# Installs SidePulse at one commit, starts its real service, and drives the plugin
# against it. The first entry has no `sidepulse report`, so the plugin must fall back to
# the device.
sidepulse:
name: sidepulse ${{ matrix.name }}
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
include:
- name: 2026-10-13, before sidepulse report
ref: ffb1d3c2f3eed3b7e80e32d7876a7e1d67bd5dfb
args: --legacy
- name: 2026-11-10, first with sidepulse report
ref: ad4a5217fd3a833cfa2a12e1eaf055f22948cd53
- name: 2026-11-12
ref: 20ca7fdd6645ba070af607e24587084b6f809275
- name: main
ref: main
steps:
- uses: actions/checkout@v6
- uses: actions/checkout@v6
with:
repository: inteliwear/sidepulse
ref: ${{ matrix.ref }}
path: upstream
persist-credentials: false
- uses: actions/setup-python@v6
with:
python-version: "3.12"
- uses: actions/setup-node@v6
with:
node-version: "24"
- run: python -m venv .venv && .venv/bin/pip install ./upstream
- run: .venv/bin/sidepulse --version
- run: node test/service.mjs ${{ matrix.args }}
env:
SIDEPULSE_BIN: ${{ github.workspace }}/.venv/bin/sidepulse

# Installs one OpenCode release and runs real turns in it with the plugin loaded.
# OpenCode's free models need no account, so there are no secrets here. 1.18.0 is the
# oldest release the free models accept.
opencode:
name: opencode ${{ matrix.version }}
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
include:
- package: opencode-ai
version: 1.18.0
- package: opencode-ai
version: 1.19.5
- package: "@opencode/cli"
version: 2.1.2
- package: "@opencode/cli"
version: 2.3.0
- package: "@opencode/cli"
version: latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with:
node-version: "24"
- run: npm install --global "${{ matrix.package }}@${{ matrix.version }}"
- run: opencode --version
- run: node test/opencode.mjs
37 changes: 37 additions & 0 deletions .github/workflows/mutation.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
name: mutation

# Mutation testing: Stryker changes the plugin one small piece at a time and reruns the
# tests. A change no test notices is a gap in the tests. The run fails when fewer than 85%
# of the changes are caught (see stryker.config.json).
#
# It takes about ten minutes, so it only runs when the plugin or its tests change.

on:
pull_request:
paths:
- plugin.mjs
- test/**
- stryker.config.json
- .github/workflows/mutation.yml
workflow_dispatch:

permissions:
contents: read

jobs:
stryker:
runs-on: ubuntu-latest
timeout-minutes: 40
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with:
node-version: "24"
# The package has no dependencies, so Stryker is fetched for this job only.
- run: npm run test:mutation
- if: always()
uses: actions/upload-artifact@v4
with:
name: mutation-report
path: reports/mutation
if-no-files-found: ignore
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1 +1,3 @@
node_modules
.stryker-tmp/
reports/
102 changes: 75 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,37 +77,46 @@ tell you things you cannot see. You already know that you cancelled it.


The green hold stays until the next turn starts. The device holds the last program, so the
plugin needs no timer to keep the color.
plugin needs no timer to keep the color. A failed turn stays red the same way.

## Two modes

The SidePulse menu-bar app also writes the LED control file. Two writers on one file
The SidePulse background service also writes the LED control file. Two writers on one file
conflict, and the device restarts its animation on every write. This plugin avoids the
conflict. It picks a mode for each event:
conflict. It picks a mode for each status change:

| Mode | Condition | Behavior |
| --- | --- | --- |
| App | The app event socket answers. | Send a hook event. Never touch `LEDS.LED`. |
| Direct | No socket answers. | Write an LED program to `LEDS.LED`. |
| App | `sidepulse report` succeeds. | Report the session status. Never touch `LEDS.LED`. |
| Direct | The command is missing or fails. | Write an LED program to `LEDS.LED`. |

Only one process ever writes the device.

In app mode the app owns the display. The app aggregates opencode together with Codex,
In app mode the service owns the display. It aggregates opencode together with Codex,
Claude, and Grok, and it shows the most actionable state across all of them. The plugin
sends these upstream event names:
pipes one [program status](https://github.com/inteliwear/sidepulse/blob/main/docs/protocol/program-status.md)
report to `sidepulse report --json` whenever a session changes state:

| Plugin signal | `hook_event_name` | App mode |
| Plugin signal | Reported state | Shown as |
| --- | --- | --- |
| Turn start | `UserPromptSubmit` | Working |
| Tool start | `PreToolUse` | Tool Running |
| Tool end | `PostToolUse` | Working |
| Permission prompt | `PermissionRequest` | Waiting For Input |
| Failure | `PostToolUseFailure` | Blocked / Error |
| Finished | `Stop` | Completed |
| Aborted | `SessionEnd` | Completed |
| Turn start, tool start, tool end | `working` | Working |
| Permission prompt | `blocked`, kind `permission` | Waiting for Input |
| Multiple-choice question | `blocked`, kind `question` | Waiting for Input |
| Prompt answered | `working` | Working |
| Failure, provider retry | `error` | Blocked / Error |
| Finished, cancelled | `done` | Completed |

The app needs no patch. Its ingest path accepts any provider name, so `opencode` appears
as a normal agent. `HOOK_PROVIDERS` in the upstream package only limits CLI arguments.
A report carries the session ID, the project directory and the state. It never carries
prompts, tool input or tool output.

The plugin reports a session only when its state changes, so a run of tool calls costs
nothing. Reports go out one at a time, in order. Any report still queued when opencode
exits is sent before the process ends, so `opencode run` still finishes green. A session
that is still working or waiting when opencode exits is cleared, because the service never
expires those states by itself.

The plugin looks for the command in `$SIDEPULSE_BIN`, then `~/.local/bin/sidepulse`, then
`PATH`. The service needs no patch: `opencode` appears as a normal agent.

Direct mode needs no Python and no app. The device exposes its controller as a file, so a
file write is the whole interface.
Expand All @@ -118,22 +127,57 @@ file write is the whole interface.
- OpenCode 2, or OpenCode 1.17.20 or newer. Older OpenCode 1 releases are not tested. If
the plugin does not load on one of them, use `opencode-sidepulse@0.1.7`.
- A SidePulse Pro or SidePulse Dot.
- For app mode, a SidePulse release that has the `sidepulse report` command. Upstream
added it on 10 November 2026. An older menu-bar app does not understand this plugin and
both would write the device, so update SidePulse or use `opencode-sidepulse@0.2.0`.

The plugin needs no dependencies and no build step. It uses only Node standard library
modules, so it runs the same under any opencode runtime.

## Test it

From a clone of this repository, under `node` or `bun`:
From a clone of this repository:

```sh
node plugin.mjs # program limits, state machine, device and socket discovery
node plugin.mjs --send # send one test event to a running app, and report delivery
npm test # the self-check, then the regression suite
node plugin.mjs --send # send one test report through the sidepulse CLI
node plugin.mjs --demo # walk every LED state on the real device, four seconds each
```

Use `--send` whenever you change the socket transport. App mode falls back to direct mode
on any failure, so a broken transport is otherwise invisible.
Use `--send` whenever you change the transport. App mode falls back to direct mode on any
failure, so a broken transport is otherwise invisible. The test report clears a session
that does not exist, so it leaves nothing in the menu.

The tests come in four layers. None of them has a dependency to install.

| Command | What it runs against | Needs |
| --- | --- | --- |
| `node test/run.mjs` | A fake `sidepulse` CLI and a folder standing in for the device. Covers both modes, the handover between them, ordering, exit, and event traces recorded from real OpenCode releases. | Nothing |
| `SIDEPULSE_BIN=… node test/service.mjs` | A real SidePulse install. Starts its service and reads back what it shows. Add `--legacy` for a SidePulse from before `sidepulse report`. | SidePulse |
| `OPENCODE_BIN=… node test/opencode.mjs` | A real OpenCode. Runs real turns on one of OpenCode's free models, which need no account. | OpenCode, network |
| `npm run test:mutation` | [Stryker](https://stryker-mutator.io) changes the plugin one piece at a time and reruns the first layer. It fails below 85% caught. | Network, about ten minutes |

The first three also run under `bun`. `test/run.mjs` takes a word to run only the tests
whose name contains it, and `--keep` to keep the files of a failed test.

CI runs all four. `compat.yml` pins the versions it checks:

| Program | Versions |
| --- | --- |
| SidePulse | The commit before `sidepulse report`, the first commit with it, a later one, and `main` |
| OpenCode 1 | 1.18.0 and 1.19.5 |
| OpenCode 2 | 2.1.2, 2.3.0 and the latest release |

The moving entries, SidePulse `main` and the latest OpenCode, also run every Monday. A
breaking change in either program then fails here first. OpenCode releases older than
1.18.0 cannot use the free models, so CI cannot run a turn in them.

When a new OpenCode or SidePulse release changes behaviour, record what it sends, add it
to `test/run.mjs` as a trace, and add the version to `compat.yml`.

Two environment variables exist for the tests. `SIDEPULSE_VOLUMES` replaces `/Volumes` as
the folder searched for the device. `SIDEPULSE_REPORT_TIMEOUT_MS` replaces the five
seconds the plugin waits for the CLI.

Without a clone, check that the published package imports:

Expand All @@ -143,25 +187,29 @@ bunx --package opencode-sidepulse bun -e \
# default opencode-sidepulse
```

That confirms the package only. Use a clone for the self-check and the demo.
That confirms the package only. Use a clone for everything else.

The LED language has no error channel. A program that fails to parse blinks all LEDs red
six times. Watch the device during `--demo` to confirm each state.

## Known limits

- Direct mode tracks one state for all sessions. Run the menu-bar app if you need true
per-session aggregation.
- Direct mode tracks one state for all sessions. Run the SidePulse service if you need
true per-session aggregation.
- If opencode is killed mid-turn, the plugin cannot clear its sessions. They stay in the
SidePulse menu as Working until the service restarts.
- App mode does not name the running tool. The service draws a running tool the same way
as Working.
- In direct mode the plugin touches `keepalive` once a minute. The MacBook SD card reader
cuts power to the device after three minutes of inactivity. The device therefore goes
dark a few minutes after you quit opencode. In app mode the app owns the keepalive.
dark a few minutes after you quit opencode. In app mode the service owns the keepalive.
- The device ignores LED indexes above its LED count. The programs target LEDs 0 to 3, so
they work on the eight-LED Pro and degrade on the two-LED Dot.

## Credits

SidePulse and its LED language come from [inteliwear/sidepulse](https://github.com/inteliwear/sidepulse) (MIT).
This plugin is an independent client of the documented file and socket interfaces.
This plugin is an independent client of the documented file and status report interfaces.

## License

Expand Down
5 changes: 3 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "opencode-sidepulse",
"version": "0.2.0",
"version": "0.3.0",
"description": "Show opencode agent status on a SidePulse Pro or SidePulse Dot LED device.",
"keywords": [
"opencode",
Expand Down Expand Up @@ -31,6 +31,7 @@
"LICENSE"
],
"scripts": {
"test": "node plugin.mjs"
"test": "node plugin.mjs && node test/run.mjs",
"test:mutation": "npx --yes @stryker-mutator/core@10.1.1 run"
}
}
Loading
Loading