@tduyng/pi-opencode-z

opencode's Zen models in pi, free ones included, with no API key and no proxy. The bridge drives the opencode server already running on the machine.

Since September 2026 the free tier answers any direct API call with 403 FreeTierError: "OpenCode's free tier can only be used from within OpenCode". No key and no proxy gets around it, because the check is on where the request originates.

So the extension does not call the Zen API. It drives the opencode background server and lets opencode make the upstream call, which is the one thing the free tier accepts.

The conversation lives in opencode

The bridge sends only the new message each turn instead of re-serialising the transcript, and the tool schemas sit in opencode's cached prefix rather than being pasted back as prose on every request.

The bridge exposes pi's tools over MCP as pi_read, pi_bash, pi_edit and so on. When the model calls one, the bridge holds that MCP request open, hands the call to pi, and pi runs the real tool against the real project. The answer goes back over the same held request and opencode carries on in the same session. The model never touches files directly.

Nothing is written to the repository. Each pi session gets one opencode session rooted in a throwaway temp directory holding its opencode.jsonc, and ~/.config/opencode is untouched.

A mode switch that adds or removes tools keeps the session too: the bridge pushes notifications/tools/list_changed over MCP, opencode re-lists, and the cached prefix survives.

The token floor

A plain opencode run on a free model spends 9,176 input tokens on a one-line prompt. This bridge spends 6,941, with 2,048 of those served from cache. That floor is opencode's own system prompt and built-in tool schemas, and every approach pays it, because stripping those tools is exactly what trips the 403.

What the bridge saves is per turn. A full tool-calling turn with a real file read takes about 10 seconds end to end.

Use

Run /model and pick anything under the opencode-z provider, for example opencode-z/mimo-v2.6-flash-free.

pi --provider opencode-z --model mimo-v2.6-flash-free

| Command | Effect | | --- | --- | | /opencode-z status | Server url, config file, models filter, MCP endpoint, live sessions, model list | | /opencode-z models | The models alone, free ones first | | /opencode-z refresh | Re-read the config and the catalogue without restarting pi | | /opencode-z config | Resolved settings and where they come from | | /opencode-z help | Usage |

Install

• The opencode CLI on PATH, or OPENCODE_Z_BIN pointing at it.
• The opencode background server. If it is not running, the bridge runs opencode service start.
• No API key and no account.

pi install npm:@tduyng/pi-opencode-z

Local checkout: pi install /path/to/dotfiles/pi/agent/extensions/pi-opencode-z

The bridge reads the server url and password from ~/.local/state/opencode/service.json and talks to it over HTTP basic auth as user opencode.

Settings live in ~/.pi/agent/opencode-z.json, and a project's .pi/opencode-z.json overrides it field by field. Environment variables override both, so a one-off run never needs a file.

Free models only:

{
  "models": "free"
}

A pinned list with a custom binary:

{
  "bin": "/path/to/opencode",
  "models": ["mimo-v2.6-flash-free", "muse-spark-1.3"]
}

models narrows what gets registered: free keeps zero-cost models, and a comma-separated string or an array pins the list. Unset or empty, every Zen model the account can reach is registered. Only Zen models appear, never other providers. OPENCODE_Z_BIN and OPENCODE_Z_MODELS do the same per process and win over the file.

It adds no tool, no prompt block and no schema, so the context is pi's own and cold start is unchanged.

Notes

The bridge never denies opencode's built-in tools. A deny rule anywhere in the agent's permissions trips the free-tier 403 even for allowed tools, so every action stays on ask and the bridge rejects the unwanted ones at runtime. A weaker model sometimes reaches for its built-in read first, gets refused, and retries with pi_read, which costs one round trip.

opencode adds and retires Zen models often, so the bridge reads the catalogue live at startup and /opencode-z refresh re-reads it.

The first prompt lists the exact MCP names available in that turn. Some model hosts display these tools under a functions. namespace, and the bridge states that the label does not rename a tool, so a model does not mistake a disabled read for pi_read.

opencode stops a whole step when the model calls two built-in tools at once, since refusing one declines the rest. The bridge counts its own refusals and, when that stop was its doing, re-prompts the same session with a nudge back to the pi_ tools, at most twice per turn.

When a turn fails, the bridge interrupts opencode and answers waiting tool calls with an error. It keeps the opencode session when pi's transcript still ends at the last completed user message, so a retry reuses the prompt cache, and drops it when a partial assistant or tool result is present.

Limits

• A turn times out at 300 seconds, and an MCP exec at 300 seconds. Large contexts on high thinking levels are slow, so a timeout usually means the model was still working.
• The API request times out at 15 seconds, and the MCP body is capped at 8 MB.
• A step that produces reasoning but no text and no tool call is re-prompted through a bounded recovery path, twice per turn at most.
• Free-tier model availability is opencode's to change. The list is read live for that reason.