English | 中文

pi-opencodego

A lightweight pi extension built for the OpenCode Go / Zen official API channel, providing three enhancements:

• ① Request compatibility filter — fixes 400 errors on some models/gateways that reject a developer role (rewrites it to system).
• ② Multi-key rotation + quota awareness + session affinity — intelligently rotates across multiple OpenCode keys to survive rate limits / bans; keeps one session pinned to one key to preserve prefix cache.
• ③ Usage / token / cache / cost tracking & visualization — records every interaction and shows quota/cost in the browser or TUI.

Design principle: touch only when needed — only rewrite when there's a compat problem, only rotate when unavailable; otherwise pass requests through untouched.

---

Install

Requires pi. Pick one:

# Option 1: npm (recommended)
pi install npm:pi-opencodego

# Option 2: GitHub
pi install git:github.com/february2015/pi-opencodego

⚠️ Security: pi extensions run with full system access. Consider reviewing the source before installing third-party packages.

Configure keys

Add your OpenCode Go / Zen keys to the pool and switch to the opencode-go channel:

/ocgo add main sk-YOUR_KEY      # add a key (multiple allowed: /ocgo add backup sk-...)
/ocgo use 1                     # set the active key (1-based index)
/model opencode-go/deepseek-v4-flash   # switch to an OpenCode Go model

Then just chat — the extension injects keys, tracks usage, and rotates to the next available key on rate limit / quota exhaustion (one session always stays pinned to one key to avoid prefix-cache invalidation).

Commands

Command	Description
/ocgo status	List all keys and states (active / cooling / banned)
/ocgo usage	Show three-window quota percent + reset time
/ocgo cost	Today's tokens, estimated cost, cache-hit rate
/ocgo add <name> <key>	Add a key
/ocgo rm <n>	Remove key (index)
/ocgo use <n>	Switch to key index
/ocgo next	Switch to next key
/ocgo reset	Clear all cooldowns / bans
/ocgo cooldown <min>	Set cooldown minutes
/ocgo watchdog [on|off|ms]	Watchdog settings
/ocgo web	Show Web panel status
/ocgo web start	Start Web panel (usually auto-started)
/ocgo web stop	Stop Web panel
/ocgo web restart	Restart Web panel
/ocgo help	All commands

Web quota panel

The extension ships a built-in browser quota panel (default port 8123) that auto-starts in the background when pi launches — no manual command needed. Open:

http://127.0.0.1:8123

Control it from inside pi:

/ocgo web status     # status + port
/ocgo web start      # manual start (usually not needed)
/ocgo web stop       # stop the panel
/ocgo web restart    # restart the panel

Each key is a card showing rolling / weekly / monthly quota bars, cooldown/ban state, and the key prefix. Two independent dropdowns in the toolbar: Page refresh (default 5s, browser rerender rate) and OpenCode fetch (default 30s, how often the backend pulls new data upstream).

Disable auto-start with env OCGO_NO_WEB=1 (e.g. testing / port conflicts).

The pi TUI also renders quota bars + a footer summary in the bottom bar (ctx.ui.setWidget() / setStatus(), TUI only).

Features

Capability A: request compatibility filter (fixes 400)

Intercepts OpenCode Go / Zen provider requests and scans for role: "developer" messages:

• Upstream doesn't support developer → rewrite to system (or merge into adjacent system message).
• Supported or absent → unchanged.
• Idempotent: already-rewritten turns are not re-rewritten; unaffected requests pass through with zero overhead. On by default, only active when developer exists.

Capability B: multi-key rotation + quota awareness + session affinity

• Key pool: register/switch multiple keys.
• Quota / state: track each key's cooldown, quota-ban, and unban time; query usage.
• Failure rotation: on 429 / quota exhaustion / silent hang (watchdog), rotate to the next non-banned key, putting the failed key into cooldown/ban; if all banned, stop and report the earliest unban time.
• Session affinity (key highlight): reuse one key within a session; only switch mid-session when that key actually fails or exhausts quota; re-pick on a new session. Goal: avoid losing the OpenCode prefix cache when switching keys mid-session (wasteful, degraded).
• Implementation only swaps the Authorization header, passing the body through unchanged (role rewrite is Capability A's job).

Capability C: usage / token / cache / cost tracking

• On each message_end, read the standard usage from the response (incl. cached_tokens / cache_write_tokens) and record it automatically.
• Go is flat-rate (cost always "0"), so cost is estimated from a built-in price table (incl. DeepSeek V4 peak/off-peak).
• /ocgo cost summarizes today/this-week tokens, estimated cost, and cache-hit rate (= cached/prompt, key metric for optimizing DeepSeek cost).

Verified API return shapes / boundaries: docs/OPENCODE-API.md.

Project layout

src/core/                    # zero-pi business logic (reusable by dsh)
├─ config.ts                 # key pool / cooldown / ban / session-affinity config
├─ keyRouter.ts              # session affinity + failure rotation + quota state machine
├─ usage.ts                  # usage API parsing + display
├─ pricing.ts                # price table + usage/cost estimate
├─ usageStore.ts             # usage records to disk + summary
├─ developerCompat.ts        # developer→system compat filter
├─ webui.ts / portfile.ts    # Web quota panel + port management
└─ index.ts                  # aggregate exports
pi/index.ts                  # pi wrapper: event hooks + /ocgo commands + Web panel auto-start
test/*.test.ts               # unit tests

Docs

Doc	Content
docs/OPENCODE-API.md	Verified official API facts (usage / token / price / peak)
docs/ARCHITECTURE.md	Layered design, pi hooks, compatibility with similar extensions
docs/DEVELOPMENT.md	Dev run, tests, acceptance criteria, roadmap

License

MIT