pi-opencode-bridge

Delegate threads from a Pi session to a local OpenCode service. oc_open returns while the thread still runs. When the thread settles, Pi opens a new turn with the answer. Your main session keeps working, and you keep the terminal.

$ pi install npm:@barty13/pi-opencode-bridge

Or from git:

$ pi install git:github.com/Barty13/pi-opencode-bridge

Then start Pi with the thread root set:

$ OC_ROOT=~/work/threads pi

> /oc
mode: supervised · service: http://127.0.0.1:… · threads: 0 armed
> oc_models
> oc_open  model: <id from oc_models>  title: refactor-parser  brief: …

What it removes

Pi runs one turn at a time, and a turn is the unit that blocks. Delegation with a blocking call holds that turn for the whole run of the other model. Here the send returns in milliseconds. The finish arrives later, as one message, with the answer already inside it.

The bridge adds seven tools and six commands.

Install

$ pi install npm:@barty13/pi-opencode-bridge      # or: pi install <path to a clone>

An update takes effect on the next restart or resume: a running pi keeps the code it loaded.

Requirements

• OpenCode already installed and signed in. Free or licensed, your choice. The service must run: start it with opencode serve --service. The bridge only talks to that local service, on the port opencode service status prints, with the password in ~/.config/opencode/service.json. It never installs, updates, or configures OpenCode, and it never reads your provider keys.
• Ghostty 1.3 or newer, for the live columns. Each live thread gets one column that runs opencode --session <id>, so you watch the thread work. Ghostty's AppleScript dictionary drives it, so this part is macOS only. Set OC_PANES=0 if you do not want columns.
• Pi 1.4 or newer. Bun runs the extension; Pi bundles it.

How a thread finishes

1. oc_send posts the prompt and returns. The thread is armed: the bridge now owes one wake-up.
2. The OpenCode event stream reports session.execution.{succeeded,failed,interrupted}. One detail request per armed thread every OC_BACKSTOP_MS covers dropped frames.
3. Detect claims the thread once, snapshots the answer, and releases one debounced message per batch. Two settles produce one message.
4. oc_wait waits on that same detector, so a collected answer never wakes the model twice.
5. A run already reported answers already reported instead of a second copy: the wake-up and oc_wait share one report per run. oc_wait with since and oc_read read the record freely.

A batch that lands while you type waits for you. A batch held by compaction waits for the compact to end. An escape (abort) holds the batch, so a wake-up cannot reopen a conversation you dropped.

Print, JSON, and a Pi reload carry no wake-up. There oc_wait is the collector.

Context ceiling

A thread that grew past OC_COMPACT_TOKENS compacts before it takes your next instruction. The bridge reads the newest assistant row of that thread (input + cache.read + cache.write + output + reasoning), orders POST /compact with delivery:"steer", then posts the prompt. OpenCode runs the compaction at the step boundary, so the prompt lands on the compacted context. Measured on a 716k thread: compact admitted in 77 ms, reply 98 s later, size down to 34k.

The receipt says so: sent; ... compact ordered at 716k. A thread whose newest compaction row postdates its last answer reads 0, so one compaction never triggers the next. OpenCode answers a second steer with 409, so parallel sends order one compaction. Your own opencode.json auto-compact stays in charge below the ceiling.

Supervision

Every ask from a thread (a permission, a form) goes to you by default. /oc-auto hands asks to the model in this Pi session, which answers with oc_reply. /oc-accept returns to you. --oc-auto starts a session in auto mode. Each session start resets to supervised and drops per-thread state, so a stale run stays safe.

Boundary

Threads live under OC_ROOT. oc_open checks the create path, every other tool checks that thread's own directory once. Real paths compare, so a symlink cannot escape the root. Threads can write files, so point OC_ROOT at a scratch tree you own. Without OC_ROOT the root is the working directory at start.

Environment

Checks

Model-free checks run against a stub pi and a stub service. Each has a control build with the fix removed, which must fail. See checks/README.md.

$ bun install
$ bun run typecheck
$ bun run check

Checks that need a real model drive a Pi TUI in tmux, and take OC_CHECK_MODEL:

$ OC_CHECK_MODEL=<id from oc_models> bash checks/check-tui.sh
$ OC_RPC_MODEL=<id from oc_models> bun run oc-rpc.ts   # wake-up path, costs tokens

Limits

• One OpenCode service per bridge, no remote host, no proxy.
• Live columns need macOS plus Ghostty. They stay off in print, JSON, and RPC mode.
• 32 open threads at most. A watch older than OC_WATCH_TTL_S expires and reports itself.
• Message bodies cap at 4000 characters per read; offset pages past the cap.
• Deleting a thread outside the bridge does not cancel its armed watch, so its wake-up still fires. Clean up after the settle with /oc-clean force, not mid-run.

Picture

assets/banner.png comes from gallery/render.py. Run bash gallery/fetch.sh first: it pulls the producers' own screens, the Pi terminal screenshot from pi-mono and the OpenCode splash and working screens from opencode. Trademarks belong to their owners. No operator screenshot appears in it.

License

MIT. See LICENSE. Report issues through SECURITY.md.