Push To Display plugin for OpenCode — mirrors your agent's activity onto your Push To Display board in real time.
Requires OpenCode V2.2+. Install the published npm package once:
opencode plugin add opencode-pushtodisplay@latestThat adds the plugin to your global opencode.json(c). The plugin includes the
Push To Display CLI it needs; there is no separate CLI or global npm install.
Security: plugins run with the OpenCode server's full system access. Review the source before installing third-party plugins.
A panel is a shared scrolling log (1 of 4). Every entry is its own message, newest at the top, and every entry has the same shape:
<agent> <what happened> <STATUS> <time>
live session closed ENDED 12:10
live Pinned the clock so the release test passes. DONE 12:09
live Allow bash: git push --force-with-lease NEEDS 12:08
live reading src/payloads.ts OK 12:08
live running grep FAIL 12:07
live running ls -1 src OK 12:07
live fix the flaky release test RUN 12:06
live session opened READY 12:06
Three things get shortened, and each is shortened by structure first:
| Body | Rule |
|---|---|
| tool description | 48 characters; a long command keeps its program and subcommand (running grep), a long path drops its directory before its file name |
| prompt | first usable sentence, 60 characters, ellipsis at a word boundary when possible |
| result | same rule as the prompt |
The agent name leads, so a shared panel reads as one column per agent; the event
follows, and the status and clock trail. A line is four inline runs on a fixed
dark surface (#1b2430): the name is teal, the body near-white, the status has
its own colour, and the time is dimmed. Type size and weight are the renderer's
defaults; the upper-case status is what makes a line scannable.
| Event | Entry | Status |
|---|---|---|
| a session is created | session opened |
READY |
| a session is renamed | session renamed |
READY |
| a prompt arrives | <task> |
RUN |
| a tool finishes | running npm test |
OK / FAIL |
| a blocking permission opens | Allow bash: git push |
NEEDS |
| the run finishes | <what the agent said> |
DONE |
| you interrupt the run | interrupted before it finished |
STOP |
| the session is deleted | session closed |
ENDED |
| the model/provider fails | HTTP 500 … |
FAIL |
The status word is a closed vocabulary — READY, RUN, OK, FAIL,
NEEDS, DONE, STOP, ENDED — so a line can never invent its own state, and
there is no icon to decode. READY and ENDED bracket a session: silence alone
cannot distinguish a finished agent from a killed one, so the panel says when it
opens and when it closes, reloads included.
Steps are posted when they finish, so a line states what actually happened instead of leaving a stale "running" behind it. The rest is deliberately silent: a turn boundary, the agent's mid-run chatter, and a prompt being answered are facts about machinery, not news.
The result line quotes the agent. Counters ("ran 5 tools", "finished in 6s")
answer a question nobody asked, so DONE carries the agent's own closing text,
shortened to its first usable sentence. It gets the same prose treatment as the
prompt; tool descriptions are summarised separately.
OpenCode reports a subagent as a child session. Child-session prompts and tool
steps are not mirrored: the parent's task step already says a delegation
happened, and duplicating the child's whole run would turn one board line into a
noisy second log. A permission request from a child still surfaces under the
parent's name, because a human must act on it.
- Reads like English — every entry is a sentence (
running npm test,editing src/auth.ts (+8 −3)). Paths are shortened against the session cwd. - A trail, not a status card — one entry per finished tool step, in the order
it happened.
/pushtodisplay-clearwrites alog clearedentry;PUSHTODISPLAY_STEPS=0drops the per-step entries if you only want milestones. - Failures are reported, never inferred — a failed step says
FAILon its own line; a provider error says what the provider said;STOPmeans you interrupted the run. There is no "the run failed" verdict to contradict a turn that finished, and no threshold that decides one. - Order is preserved — nothing is reordered, so a result is never sent ahead of the step that caused it. Consecutive duplicates are suppressed, and the backlog is bounded, so the log cannot fall minutes behind the agent.
- OAuth-only auth — no API keys. Reuses the
pushtodisplayCLI's device-code flow; tokens auto-refresh. - Quota-friendly — every API call counts toward your message quota (Sandbox tiers are rate-limited to ~1 msg/s). Sends are spaced ≥ 1.2 s, consecutive identical lines are skipped per agent, and nothing streams token by token.
- Explicit setup — a shared login is not enough. A fresh install stays
silent until
/pushtodisplay-setupverifies auth and sends a test entry. - Auth gating — updates wait for the first auth probe, then are dropped (never buffered) while auth is known to be bad; sending resumes automatically once you log in.
- Self-contained install — ships the pinned Push To Display CLI inside the plugin, so one npm install is all you need.
- OpenCode V2.2+ with
@opencode/plugin2.2.x. - Node.js ≥ 18 for the bundled
pushtodisplayCLI and for development. OpenCode loads the plugin's TypeScript entry directly; there is no build step. - A Push To Display account and board.
After installing, run the one setup action:
/pushtodisplay-setup
It logs in with the OAuth device-code flow if needed, sends one test entry to your configured panel and board, and only then enables automatic updates. If you already logged in through another integration on this machine, setup reuses that login but still sends the OpenCode test entry and marks this installation as set up.
The board should show <label> link OK, panel N OK HH:MM. Check the current
state at any time with:
/pushtodisplay-status
Use /pushtodisplay-login only when you need to re-authenticate; it does not
clear an existing setup marker.
That's it — the next time you run an agent, your board shows it starting, what it's working on, errors, and when it ends.
Environment variables and plugin options both work. Plugin options win over
the environment, which makes it easy to run several OpenCode projects with
different panels from one shell.
| Env var | Plugin option | Default | Description |
|---|---|---|---|
PUSHTODISPLAY_BOARD_ID |
boardId |
(default board) | Board ID to send to. |
PUSHTODISPLAY_PANEL |
panel |
1 |
Which panel (1–4) this agent writes to. |
PUSHTODISPLAY_LABEL |
label |
(session title, then folder) | Agent name in the first field of every line. |
PUSHTODISPLAY_STEPS |
steps |
(on) | Set to 0 / false to skip per-tool entries (milestones only). |
PUSHTODISPLAY_DISABLED |
disabled |
(off) | Set to 1 / true to disable the plugin entirely. |
Example opencode.json(c):
Give each parallel OpenCode process its own panel and a label:
# agent A
PUSHTODISPLAY_PANEL=1 PUSHTODISPLAY_LABEL=cicd opencode
# agent B
PUSHTODISPLAY_PANEL=2 PUSHTODISPLAY_LABEL=qa opencodeEach panel becomes its own scrolling log, so you can see what every agent did and which one needs you. Sharing a panel between agents is fine — the agent field on every line keeps them apart:
qa Allow bash: git push NEEDS 11:41
release running npm test OK 11:40
TIP: with no explicit
PUSHTODISPLAY_LABEL, the label is the session title when one is set, otherwise the workspace folder name; launching from two different repos already gives you two distinct agents.
| Command | Description |
|---|---|
/pushtodisplay-setup |
Log in if needed, send a test entry, and enable updates for this OpenCode install. |
/pushtodisplay-login |
Re-authenticate (OAuth device-code flow) without clearing setup. |
/pushtodisplay-status |
Show current auth and setup state. |
/pushtodisplay-test |
Send a test update to verify wiring. |
/pushtodisplay-clear |
Write a log cleared entry to this panel. |
Command output is written back with ctx.session.synthetic, so it appears in the
session transcript without being sent to the model or to the board.
OpenCode events ──► state ──► message builder ──► sender ──► CLI ──► API
(session/task/ (panel-state) (messages.ts, (ordered, (1.2s spacing) (OAuth)
tool/permission/ one sentence) bounded,
text/idle) deduped)
- Events listened to:
session.created,session.renamed,session.deleted,session.execution.failed,session.execution.interrupted,session.execution.succeeded,session.idle,session.text.ended,permission.asked, andlocation.shutdown. OpenCode 2.2 reports a settled run withsession.execution.succeeded;session.idleis kept as a fallback for versions that emit it. - Hooks:
ctx.session.hook("prompt", ...)turns an admitted prompt into theRUNline;ctx.tool.hook("execute.after", ...)turns each finished tool into itsOK/FAILstep. - Messages, not state:
src/messages.tsturns one event into one sentence. There is no "current status" object to render —PanelStateis four fields (agent,cwd,task,closing). - No coalescing: every entry is news, so nothing is dropped for being superseded.
- One queue, four jobs:
src/sender.tskeeps strict order, suppresses consecutive duplicates, trims the oldest steps when the backlog would otherwise run too far behind, and spaces sends ≥ 1.2 s apart — safely above the Sandbox ~1 msg/s cap. - Setup gating: updates are sent only when this OpenCode integration has a
setup marker and auth is valid. The marker is written by
/pushtodisplay-setupafter its test entry succeeds, so a shared credential from another integration cannot make a fresh install start posting. - Auth gating: auth is probed at plugin load and re-probed lazily on send at
most once every 20 s while unauthenticated (
/pushtodisplay-statusforces a check). Once auth is known to be bad, updates are dropped, never buffered;/pushtodisplay-setupor/pushtodisplay-loginre-probes and re-enables sending. Gating happens at dispatch time, so every path is covered. - Cleanup: when the plugin unloads (including server shutdown), it flushes
the sender and writes
ENDEDfor every session it opened.
| Symptom | What to check |
|---|---|
Push To Display CLI not found |
The plugin install looks incomplete — reinstall opencode-pushtodisplay, then run /pushtodisplay-setup. |
| Nothing appears after installing | Run /pushtodisplay-setup; a fresh install stays silent until the marker and auth both exist. |
| Authenticated but still silent | Run /pushtodisplay-setup to finish this OpenCode install, then /pushtodisplay-status. |
| Updates paused / not authenticated | Run /pushtodisplay-setup, then /pushtodisplay-status. |
| Test entry does not appear | Run /pushtodisplay-setup or /pushtodisplay-test; check PUSHTODISPLAY_BOARD_ID, PUSHTODISPLAY_PANEL, and the agent label. |
| Only milestones, no tool lines | PUSHTODISPLAY_STEPS=0 or "steps": false is set. |
| Plugin does nothing | PUSHTODISPLAY_DISABLED=1 or "disabled": true is set. |
| Login URL/code never appears | The CLI writes device-code instructions to stderr; the plugin shows both in a login dialog. Check the OpenCode server log for [pushtodisplay] messages. |
/pushtodisplay-test fails |
The toast includes the CLI error. Full server log: ~/.local/share/opencode/log/opencode.log; run OpenCode with --print-logs to include plugin [pushtodisplay] stderr. |
| Board lines lag behind the agent | Sends are rate-limited to ~1 msg/s; the sender drops the oldest steps when the backlog is too long. Results and milestones are never dropped. |
Lines show FAIL but the run finished |
Check whether the provider actually failed; FAIL is only written from a failed tool or session.execution.failed. A user interrupt is STOP. |
npm install
npm run check # typecheck + lint + test
npm test -- --coverageThe package is plain TypeScript — OpenCode loads src/index.ts directly (no
build step). Unit tests live under src/__tests__/ and use Jest with ts-jest.
Tests that touch the CLI use a fake pushtodisplay executable on a temporary
PATH that records argv to a file; no live OAuth or network call is made.
Extension tests use a fake OpenCode context and a mocked CLI adapter to exercise
the event, hook, command, and cleanup wiring.
Local-checkout install, bundled CLI resolution, the live smoke test, and release steps are in docs/maintainers.md and docs/publishing.md.
| File | Responsibility |
|---|---|
src/index.ts |
Package entry — resolves the bundled CLI and exports Plugin.define(...). The only file using import.meta. |
src/extension.ts |
The setup factory: OpenCode event/hook/command wiring, setup/auth gating, send scheduling, cleanup. |
src/setup-state.ts |
Per-OpenCode setup marker: cache path, read gate, atomic write. |
src/config.ts |
Env-var and plugin-option config parsing + string helpers (truncate, clock). |
src/panel-state.ts |
The task/closing text a message needs; no counters, no verdict. |
src/messages.ts |
One-sentence message builders — the whole visible vocabulary. |
src/events.ts |
OpenCode event shapes and their payload mapping. |
src/sender.ts |
The queue: order, dedupe, bounded backlog, 1.2 s spacing. |
src/payloads.ts |
Wire types and the palette. |
src/auth-gate.ts |
Unknown / logged in / logged out; unknown waits for the probe, known-bad drops. |
src/cli-adapter.ts |
Bundled CLI resolution, argv mapping, auth probing, error classification. |
src/describe.ts |
Human-readable present-tense one-liners for OpenCode tool calls. |
MIT. PushToDisplay is a product of Goban Source, LLC — see pushtodisplay.com.
{ "$schema": "https://opencode.ai/config.json", "plugins": [ { "package": "opencode-pushtodisplay", "options": { "boardId": "board_abc123", "panel": 2, "label": "qa", "steps": false } } ] }