opencode-bridge: Instructions file for Codex

opencode-bridge

MCP server that lets Claude Code delegate coding tasks to external models running on a local opencode serve. Goal: use cheaper models for implementation work, keeping the main model for planning and review.

Claude Code  --MCP stdio-->  opencode-bridge  --HTTP/SSE-->  opencode serve  -->  delegated model

v2 architecture

Rebuilt to fix three chronic failures: sessions would freeze silently, delegations came back empty, and the status field lied. In ten lines:

• Completion by event (SSE): the bridge listens to GET /event and concludes on session.idle — the primary signal, measured. Polling /session/status is only a safety net, with a double-check (status + stable tool-call count + stable completion timestamp).
• Scope by directory: every read endpoint on the serve is filtered by ?directory=. The bridge resolves the real scope via GET /session/{id} (the only endpoint that is not filtered) and repeats it on every subsequent call. Read docs/APRENDIZADOS.md §3 before touching any HTTP call.
• Hard wait ceiling (45 min, OPENCODE_MAX_POLL_MS): there is never an eternal hang; when it gives up, the bridge says explicitly that it gave up on the wait, not on the session.
• Empty-response retry (refetch + one conditional nudge) and error classification on both legs — a session that dies with an error comes back as an error, never a silent empty success.
• Self-heal: serve down → the bridge revives it through the scheduled task and retries the call.
• Auth: mandatory Basic Auth, credential read at runtime from %USERPROFILE%\.config\opencode\serve-auth.json. No secret in source.
• Single source of MCPs: scripts/sync-opencode-config.ps1 generates the mcp block of opencode.json from the Claude Code config, with the exception map declared in sync-overrides.json (gitignored; example in sync-overrides.example.json).
• Canary: if a wait concludes via polling without ever having seen busy, the bridge shouts in the log — the status gate may be blind.