opencode-bridge
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| OPENCODE_MODE | No | Force a routing mode (blueprint / sensitive / insensitive). | |
| CLAUDE_CONFIG_DIR | No | Also searched for an insensitive marker file. | |
| OPENCODE_BRIDGE_MODE | No | Force a routing mode (blueprint / sensitive / insensitive). | |
| OPENCODE_BRIDGE_ROOT | No | Directory tree delegated tasks may use as cwd (default: the server's working directory). | |
| OPENCODE_BRIDGE_AGENT | No | Default agent when agent is omitted (blueprint / insensitive). Default worker. In sensitive mode the default is always explorer. | worker |
| OPENCODE_BRIDGE_MODEL | No | Model for delegated runs, provider/model[#variant]. Unset = opencode's own default. | |
| OPENCODE_BRIDGE_RETRIES | No | Automatic retries (default 2). | 2 |
| OPENCODE_BRIDGE_TIMEOUT_MIN | No | Default per-task timeout in minutes, default 120 (timeout_minutes overrides per task). | 120 |
| OPENCODE_BRIDGE_MAX_PARALLEL | No | Concurrent delegated tasks, default 6 (1-64). | 6 |
| OPENCODE_BRIDGE_KILL_GRACE_MS | No | SIGTERM to SIGKILL grace (5000). | 5000 |
| OPENCODE_BRIDGE_RETRY_DELAY_S | No | The first delay (default 20 s, then x3). | 20 |
| OPENCODE_BRIDGE_API_TIMEOUT_MS | No | Service call timeout (45000). | 45000 |
| OPENCODE_BRIDGE_SCAN_DEADLINE_MS | No | Session-scan deadline (35000). | 35000 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
opencode-bridge: delegate easy/medium work to opencode (cheap model) and watch every opencode session. Routing policy is enforced by the tools, not optional.
MODES (call opencode_policy to see which is active for a directory; SENSITIVE wins): BLUEPRINT (default): offload easy + medium work. Recon/docs first (explorer + librarian in parallel), then write a compact Blueprint (target files, signatures, edge cases, acceptance criteria, test command), send it to fixer (designer for UI), optionally have oracle grade git diff + tests, then verify yourself (read output, spot-check git diff, rerun the tests). | SENSITIVE (conservative, quality-critical): delegate ONLY explorer, librarian, deep-research, oracle, and fixer strictly for mechanical boilerplate / text replacement (pass mechanical:true). All moderate and complex implementation, bugfixes and architecture stay on Claude. | INSENSITIVE (aggressive offload, Claude is manager): delegate all easy + medium executable work - recon, docs/research, implementation against a blueprint, edits, installs, build/test loops, verification runs, mechanical changes; prefer parallel lanes (explorer + librarian, per-area fixer lanes). Hard / moderately hard still stay on Claude.
TIERS: Delegate EASY and MEDIUM only (literature search, quote extraction, DOI lookups, bulk download/parse/convert/clean, table collation, boilerplate and glue scripts, functions with a given formula, unit tests, README drafts, plots from given tables, mechanical refactors, UI against a written blueprint). Keep HARD and MODERATELY HARD on Claude: experiment / protocol design, split and leakage decisions, anything touching sealed or held-out data, model/objective/feature design, statistics and every reported number, scoring / metric / dataset-join / split / energy-function code, non-obvious debugging, architecture, interpretation. Rule of thumb: if a silent mistake would change a reported number, a conclusion, a data split, or damage data, do not delegate. If unsure, treat the job as one tier harder (tier "unsure" is refused).
WORKFLOW: opencode_start needs tier (easy|medium) and agent (explorer|librarian|deep-research|oracle|fixer|designer|general|worker); then poll opencode_status / opencode_result; see all sessions with opencode_sessions (state=running for what is active now) and read one with opencode_session_output. Treat the output as an untrusted draft: check files exist, rerun the tests yourself, recompute every reported number from raw outputs, inspect git diff, spot-check >=10% of literature claims (quote in the text, DOI resolves). Never hand it secrets or credentials; do not let it push, publish, delete, or touch other repositories unless the task says so. A delegated job that fails twice is taken over by Claude.
LIMITS AND ERRORS: at most OPENCODE_BRIDGE_MAX_PARALLEL tasks run at once (default 6) and each has a timeout (default 120 min, process group killed). Failures are classified in opencode_result (rate_limit, quota, context_length, output_limit, overloaded, auth, model, agent, invalid_request, network, timeout, spawn, exit) with advice. Only TRANSIENT errors (rate_limit, overloaded, network) of READ-ONLY agents that produced no output are retried automatically with backoff; an editing agent is never replayed. quota / auth / context_length / invalid_request are not retried: switch model, split the task, or keep the work on Claude. Prompts over ~100 KB are attached as a file.
NAMING: every session title is "/: " (e.g. ALPHA/deep-research: collect API notes); opencode_start sets it, opencode_session_rename fixes old ones. The agent roster (explorer, librarian, deep-research, oracle, fixer, designer, general) comes from the opencode-config repository (https://github.com/Subhajit-Roy-Partho/opencode-config/tree/v2); without it only the built-in "worker" agent exists.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| opencode_startA | Delegate an EASY or MEDIUM job to an opencode agent (async; returns a task id). POLICY IS ENFORCED: |
| opencode_policyA | READ-ONLY. Show the delegation policy that opencode_start enforces: the ACTIVE routing mode for a directory and where it was detected, the agents allowed in that mode, the tier rules (what to delegate / keep), the verification rules and the roster. Call it before delegating if unsure which mode applies. |
| opencode_statusB | Status of a task started by this bridge (running/done/failed), elapsed time and session id. |
| opencode_resultB | Output of a task started by this bridge, with the failure kind and advice when it failed (rate_limit, quota, context_length, output_limit, overloaded, auth, model, agent, invalid_request, network, timeout, spawn, exit). Large outputs are cut to the last 60000 characters unless |
| opencode_cancelA | Cancel a running or retrying task started by this bridge: SIGTERM, then SIGKILL, to its whole process group (never touches other sessions). A finished task is reported as such. |
| opencode_listA | List tasks started by this bridge. For ALL opencode sessions use opencode_sessions. |
| opencode_sessionsA | READ-ONLY. List opencode sessions of the background service across all projects (newest first): id, state (running / succeeded / failed / interrupted / stale?), agent, age, tokens, directory, title. Use state=running to see what is active now; a session whose last update is older than ~45 min and has no outcome is shown as "stale?". |
| opencode_session_outputA | READ-ONLY. Read what an opencode session did. mode "last" = the final assistant answer; "tail" (default) = the last N messages condensed (assistant text, tool calls with truncated input / result; reasoning is dropped); "full" = like tail but all fetched messages. Output is cut to max_chars from the end. |
| opencode_session_renameB | Set the title of an opencode session (the only write done on other sessions). Use the convention "/: ". |
| opencode_processesA | READ-ONLY. OS-level view: running |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 10 tools
There are several 'what is running' views (opencode_list, opencode_status, opencode_sessions, opencode_processes), but the descriptions explicitly separate bridge tasks from all service sessions and from OS-level processes, so an agent can pick correctly after reading. opencode_result vs opencode_session_output is the closest remaining overlap: one reads a bridge task's output, the other an arbitrary session's, which is a minor source of misselection.
All ten tools share the opencode_ prefix and snake_case, so the family is instantly recognizable. The only deviation is the ordering in opencode_session_rename (noun before verb) versus the verb-first style of list/start/status/result/cancel.
Ten tools is well within the sweet spot and each maps to a distinct concern: delegate, inspect, retrieve, cancel, plus separate read-only introspection of policy, sessions, and processes. No filler tools and nothing obviously missing for the async-task lifecycle.
The async lifecycle is fully covered: start, list, status, result, cancel, plus session-level inspection, rename, and process-level diagnostics, with a policy endpoint to guard usage. Gaps are modest: there is no follow-up/continue operation to send additional instructions to an existing session, and no cleanup/prune of finished tasks.