You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Proposal: OpenCode CLI as an External CLI provider
#742
This is a design proposal. Per CONTRIBUTING, I am raising it before implementation and will wait for direction.
Summary
Add a core opencode-cli provider next to Claude Code, so teaching and practice sessions can run on an installed OpenCode CLI. Settings -> Providers -> External CLI would gain an OpenCode CLI toggle, off by default.
Motivation
LearnHarness already has opencode (Zen) and opencode-go, but those are API-key routes only. Anyone who has models, authentication, local providers (for example Ollama), or free tiers configured in OpenCode cannot use that setup for lessons. Claude Code is the existing precedent: the CLI owns authentication, routing and billing, while LearnHarness streams the conversation and keeps its own transcript.
Why this needs core
I read the 0.6.1 plugin API contracts/SDK and upstream main. Plugins can register views, settings pages, instructions/tools for existing agents, question and problem types, managed agents, and workers. They cannot register a model provider or hook the chat engine. A plugin therefore cannot add the External CLI toggle or route lessons through OpenCode.
Proposed behavior
Placement:Settings -> Providers -> External CLI -> OpenCode CLI, off by default, with installation/version status and Check again, mirroring Claude Code. Provider id opencode-cli (distinct from opencode / opencode-go).
Discovery and status:opencode on PATH plus common install locations (mise shims, npm global, ~/.local/bin, Homebrew, Nix). The check runs only opencode --version (parse opencode vX.Y.Z), never authentication or inference.
Transport:opencode acp over stdio. ACP provides streamed deltas, tool-call updates, token/context usage, cancellation and session resume. opencode run --format json only emits completed messages, so it cannot drive a streaming UI.
Sessions: one ACP session per active LearnHarness chat with idle expiry. The LearnHarness transcript stays authoritative; after expiry or restart a fresh session is created and history replayed.
Models:opencode models is fast and read-only; the catalog is read at startup and refreshed by Check again. Each provider/model becomes a picker entry and is selected with session/set_config_option (model).
Instructions: an ephemeral OPENCODE_CONFIG defines a custom primary agent learnharness carrying the LearnHarness system prompt, selected through the mode config option. ACP has no systemPrompt capability, so this appears to be the only injection route.
Tools: LearnHarness tools are exposed through a loopback MCP bridge (same pattern as the Claude Code bridge), injected via config with codemode: false. OpenCode's built-in tools are denied through permissions / policies; only bridge tools are allowed. Ambiguous tool-call correlation fails closed.
Isolation: ephemeral config, OPENCODE_DISABLE_PROJECT_CONFIG=1, temporary working directory, per-chat temporary OPENCODE_DB. The user's OpenCode auth, providers and models still apply. One caveat: the global ~/.config/opencode/AGENTS.md still loads into the session.
Accounting: unpriced, like Claude Code, because the CLI determines charges. Tokens are mapped, and the real context size is taken from usage_update.
Probe notes (OpenCode 2.3.0, Linux)
initialize returns loadSession, mcpCapabilities.http, promptCapabilities.{image,embeddedContext}, sessionCapabilities.{additionalDirectories,close,delete,fork,list,resume}. There is no systemPrompt capability.
session/new returns configOptions with live model and mode lists; a custom agent appears as a mode. session/set_config_option works for both.
An MCP server injected through session/new.mcpServers ignores codemode: false; injecting it through the config works.
opencode models prints provider/model lines in about 66 ms; opencode --version prints opencode v2.3.0.
2.1.0, 2.2.x and 2.3.0 all expose the required ACP/config surface in a handshake probe; 2.3.0 is the version tested end-to-end.
Open questions
Is core the right home for this, or should it wait for provider registration in the plugin API?
Is catalog refresh at startup plus manual Check again enough?
OpenCode owns compaction; what contextWindow placeholder should the host use before usage_update arrives?
Minimum version: 2.3.0 (tested end-to-end) or lower? A 2.1.0 handshake already exposes the required surface.
Is unpriced cost reporting acceptable?
Global AGENTS.md leakage: accept and document, or add isolation?
Implementation sketch
src/core/contracts/opencode-cli.ts; src/agent/opencode-cli/{binary,installation,acp-client,stream,tool-bridge,config,session,provider}.ts; src/server/opencode-cli{,-config}.ts; app/api/opencode-cli/route.ts; settings schema plus models.ts registration; settings component; docs/opencode.md plus docs index; synthetic ACP/MCP tests.
Status
Nothing implemented. If the direction is welcome I can prepare a focused PR; if you would rather keep this out of core, I would appreciate knowing before any work starts.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
This is a design proposal. Per CONTRIBUTING, I am raising it before implementation and will wait for direction.
Summary
Add a core
opencode-cliprovider next to Claude Code, so teaching and practice sessions can run on an installed OpenCode CLI. Settings -> Providers -> External CLI would gain an OpenCode CLI toggle, off by default.Motivation
LearnHarness already has
opencode(Zen) andopencode-go, but those are API-key routes only. Anyone who has models, authentication, local providers (for example Ollama), or free tiers configured in OpenCode cannot use that setup for lessons. Claude Code is the existing precedent: the CLI owns authentication, routing and billing, while LearnHarness streams the conversation and keeps its own transcript.Why this needs core
I read the 0.6.1 plugin API contracts/SDK and upstream
main. Plugins can register views, settings pages, instructions/tools for existing agents, question and problem types, managed agents, and workers. They cannot register a model provider or hook the chat engine. A plugin therefore cannot add the External CLI toggle or route lessons through OpenCode.Proposed behavior
Settings -> Providers -> External CLI -> OpenCode CLI, off by default, with installation/version status and Check again, mirroring Claude Code. Provider idopencode-cli(distinct fromopencode/opencode-go).opencodeonPATHplus common install locations (mise shims, npm global,~/.local/bin, Homebrew, Nix). The check runs onlyopencode --version(parseopencode vX.Y.Z), never authentication or inference.opencode acpover stdio. ACP provides streamed deltas, tool-call updates, token/context usage, cancellation and session resume.opencode run --format jsononly emits completed messages, so it cannot drive a streaming UI.opencode modelsis fast and read-only; the catalog is read at startup and refreshed by Check again. Eachprovider/modelbecomes a picker entry and is selected withsession/set_config_option(model).OPENCODE_CONFIGdefines a custom primary agentlearnharnesscarrying the LearnHarness system prompt, selected through themodeconfig option. ACP has nosystemPromptcapability, so this appears to be the only injection route.codemode: false. OpenCode's built-in tools are denied throughpermissions/policies; only bridge tools are allowed. Ambiguous tool-call correlation fails closed.OPENCODE_DISABLE_PROJECT_CONFIG=1, temporary working directory, per-chat temporaryOPENCODE_DB. The user's OpenCode auth, providers and models still apply. One caveat: the global~/.config/opencode/AGENTS.mdstill loads into the session.usage_update.Probe notes (OpenCode 2.3.0, Linux)
initializereturnsloadSession,mcpCapabilities.http,promptCapabilities.{image,embeddedContext},sessionCapabilities.{additionalDirectories,close,delete,fork,list,resume}. There is nosystemPromptcapability.session/newreturnsconfigOptionswith livemodelandmodelists; a custom agent appears as amode.session/set_config_optionworks for both.session/updatedeliversagent_message_chunk,agent_thought_chunk,tool_call/tool_call_update,usage_update(used,size,cost); prompt responses also carry token usage.session/new.mcpServersignorescodemode: false; injecting it through the config works.opencode modelsprintsprovider/modellines in about 66 ms;opencode --versionprintsopencode v2.3.0.Open questions
contextWindowplaceholder should the host use beforeusage_updatearrives?AGENTS.mdleakage: accept and document, or add isolation?Implementation sketch
src/core/contracts/opencode-cli.ts;src/agent/opencode-cli/{binary,installation,acp-client,stream,tool-bridge,config,session,provider}.ts;src/server/opencode-cli{,-config}.ts;app/api/opencode-cli/route.ts; settings schema plusmodels.tsregistration; settings component;docs/opencode.mdplus docs index; synthetic ACP/MCP tests.Status
Nothing implemented. If the direction is welcome I can prepare a focused PR; if you would rather keep this out of core, I would appreciate knowing before any work starts.
All reactions