OpenCode provider (run sessions in OpenCode's harness)
Run Claude-Code-style sessions through OpenCode, a separate coding-agent CLI that talks to whatever model you point it at. Set up with the binary plus your own provider keys; there is no dedicated sidebar project for it, so an OpenCode session lives inside a real project like any other.
On this page
What it is
Omniscio can spawn Claude-Code-style sessions backed by the OpenCode CLI (opencode) as an alternative provider, alongside claude (the default), codex, gemini, antigravity, the Anthropic-compatible deepseek / kimi / glm / minimax / meta, cursor, hermes, grok, pi, and openclaw (the registry defines 26 session-provider keys, 20 of them user-selectable/pickable; the non-pickable ones include the managed-PTY terminal engine and the internal-only openclaw). OpenCode is a model-agnostic local CLI harness: by default it runs Claude (Sonnet) through an Anthropic key, but it can also run any hosted model OpenCode supports (Kimi, GPT, DeepSeek, …) via the OpenCode model picker — Omniscio sends the chosen model to the shared server as the {providerID, id} selector on POST /session and routes the matching provider credential by the model-id prefix. So an OpenCode session is "an agent harness you can point at any model"; left on the default it's "Claude, driven by a different harness." Model routing is locked by provider-registry-contract.md.
Where to find it
Settings → Accounts — the OpenCode section is visible when Show alternative AI providers is on. That switch is on for fresh installs; if your saved setting is off, turn it on there. Once revealed it appears as a provider in the normal session-creation pickers.
How it behaves
What the user sees
An OpenCode session looks almost identical in the sidebar and main pane to a Claude session — same status dots, same streaming bubbles, same Ctrl+Enter to send. The differences:
- OpenCode icon in the header. An OpenCode session shows the OpenCode mark (its published logo, in the theme text color, no text label) next to its title — like every non-default provider (Codex, Gemini, Anti-Gravity, Cursor, DeepSeek, Kimi, GLM, MiniMax, Hermes, Pi). Only the internal-only engines (OpenClaw, orchestrator) show no icon — every other session, Claude included, shows its engine mark. A fresh session's Change-provider button shows the same mark while OpenCode is the selected provider.
- Streaming is token-by-token. Omniscio subscribes to the shared
opencode serveserver's Server-Sent-Events stream, so the reply appears incrementally as it generates (like Gemini, unlike Anti-Gravity's block mode). When the turn completes, one final push replaces the bubble with the full accumulated text. - Compactions are visible (2026-09-11). When a long OpenCode session fills its context window, OpenCode rewrites the history into a summary and older turns stop existing. It announces that with a
session.compactedevent, which Omniscio used to drop as an unknown frame — so the rewrite left no trace in the transcript at all. The summary OpenCode writes for itself is never shown as the agent's reply (its cost is still counted). Now it writes the same “Conversation compacted” divider a Claude or Codex session shows, carrying the context size from the last assistant message. Two differences from Claude: there is no pulsing “Compacting…” pill (OpenCode announces the rewrite only once it is DONE — there is no start signal to hang one on), and the divider has no “Show summary” button, because that reads Claude's own on-disk transcript and OpenCode keeps none. See compaction-summary.md. - Tool-use auto-approval defaults to ON. OpenCode runs its tools (file writes, shell commands, network) without per-call prompts. The "Allow OpenCode sessions" toggle gates whether you can spawn it at all; once spawned, it does not ask before acting.
How to enable
Master toggle required first. OpenCode is an alternative provider — on a fresh install OpenCode is already visible (the master toggle is ON by default since 2026-10-03); on a profile that last saved before that setting existed the entire OpenCode setup section stays hidden in Settings → Accounts until you flip it on. Flip Settings → Accounts → Show alternative AI providers to ON and the OpenCode (CLI provider) panel appears. With the master off, the per-launch provider switcher (ChangeProviderButton) hides OpenCode — it effectively does not exist in the UI even if every gate below is configured. Your "Allow OpenCode sessions" toggle and saved key are preserved across master-toggle flips.
Fastest path — "Set it up for me." The OpenCode panel leads with a Set it up for me button: one click turns OpenCode on, installs the
opencodeCLI for you (npmopencode-ai, with a Windows winget fallback), and reuses an Anthropic API key you already have saved (with a one-click confirm — never a silent copy), defaulting to Claude Sonnet so only that one key is needed. If you have no key saved, it installs + enables OpenCode and stops with a durable in-card status line ("one step left — paste your Anthropic API key below to finish") and the key field revealed. Every outcome — ready, one-step-left, or an install error — shows that persistent result line right in the card (not just a transient toast), so the click is never silent. The three manual gates below are exactly what that button automates — governed byprovider-registry-contract.md.
Three gates must all pass (getProviderSpawnReadiness enforces them in this order):
The toggle leads and gates the panel UI. The CLI-install status card and the API key field render only once "Allow OpenCode sessions" is on — so a key can't be entered into a disabled provider. When off, a hint stands in and keeps the
opencode-binary/opencode-api-keySettings-search anchors landable; a saved key is preserved.
- Allow OpenCode sessions toggle — off by default. Same security stance as the other auto-approving providers: enable only because you intend to use it. Lives in the OpenCode panel as Allow OpenCode sessions in any project, and it's the first thing you see (turning it on reveals the steps below).
- OpenCode CLI binary — the
opencodebinary must be on your PATH. The Set it up for me button installs it for you (npmopencode-ai, binopencode) and clears the binary-resolver cache so the fresh install is seen immediately. The Settings panel shows OpenCode CLI: Installed (version X) in the binary status card, or a "not found on your PATH" hint. To install by hand, runnpm install -g opencode-ai. Omniscio speaks OpenCode 1. The npmopencode-aipackage only ever carries OpenCode 1 (OpenCode 2 ships separately as@opencode/cli), but Homebrew'sopencodeformula is OpenCode 2, so Omniscio never updates OpenCode through Homebrew. The resolver also discovers an npm-global install vianpm root -g, so a GUI-launched Omniscio with a narrow PATH still finds it. (OpenCode is registered in Omniscio's toolchain installer withdefaultSelected:false— installable on demand, never auto-installed in the first-run "install recommended tools" sweep.) - The API key for the selected model's provider. Readiness is now model-aware: the key required depends on the OpenCode model you pick (gate 4). On the default (no model chosen) it's the OpenCode API Key (Anthropic) — OpenCode runs Claude through it. Pick a non-Claude model and the gate asks for that provider's key instead (e.g. an OpenRouter key for
openrouter/…). All keys are stored encrypted (safeStorage+enc:prefix) and injected as the matching environment variable on spawn (ANTHROPIC_API_KEY/OPENROUTER_API_KEY/OPENAI_API_KEY/MOONSHOT_API_KEY) — never on the command line.
Gate 4 — OpenCode model (optional). A dropdown of curated models (Claude Sonnet, GPT-4o, Kimi K2, DeepSeek…) plus a Custom… box for any provider/model id OpenCode supports. Changing a running session's model takes effect on its very next message. Leave it on the default and nothing changes — OpenCode keeps its own Claude-Sonnet default with your Anthropic key (the same outcome as before this feature; the server still gets the resolved default model selector, never a literal --model arg). Choosing a model routes the matching key by its prefix:
| Model prefix | Env var injected | Key read from (your settings) |
|---|---|---|
anthropic/… (default) |
ANTHROPIC_API_KEY |
OpenCode API Key |
openrouter/… (catch-all) |
OPENROUTER_API_KEY |
OpenRouter API Key (field in this panel) |
openai/… |
OPENAI_API_KEY |
OpenAI key (Codex's) |
moonshotai/… |
MOONSHOT_API_KEY |
Kimi key |
OpenRouter is the catch-all — one OpenRouter key unlocks Kimi, GPT, Claude, and hundreds more as openrouter/<vendor>/<model>, so you rarely need per-vendor keys. Cost guard: the OpenRouter route reads your saved key only — never Omniscio's bundled internal OpenRouter key — so a coding session can't bill Omniscio's shared account. Local models (Ollama/LM Studio) are not yet supported in v1 → they surface a model-unsupported gap rather than a confusing CLI failure.
Once all three are green, you launch an OpenCode session two ways:
- Per-launch override — on a fresh (zero-message) session, the Change-provider button in the new session's main panel (the launch-config pickers on a fresh session) lets you pick a one-off provider before sending the first message. Pick OpenCode and the first send spawns it. Non-ready providers appear disabled with a "Set up…" / "Install…" / "Add key" suffix that deep-links to the relevant Settings panel.
- Programmatically — anything that creates a session with
provider: 'opencode'(recipes, the CLI control server, agent-driven sessions). The same three readiness gates apply on the backend.
No per-project default, no virtual project
OpenCode is intentionally excluded from two surfaces that the persistent providers (Codex, Gemini, Anti-Gravity) have:
- Not a per-project default. The Edit-Project "Default provider" radios and the sidebar "+ New Session" split-button omit OpenCode (it is
pickable: false, so it is absent fromPROVIDER_ORDER). It is now a persistent shared-server engine (like Codex / Gemini / Anti-Gravity), but it has simply not been wired into the project-default surface yet. Launch it explicitly per-session instead. - No dedicated virtual project. There is no
__opencode__sidebar entry (unlike__codex__/__gemini__/__antigravity__), and therefore no sentinel bypass of the "Allow OpenCode sessions" toggle. The toggle always applies.
Error states and fixes
Gap codes (toggle + binary as before; key-missing is now per-selected-model; model-unsupported is new):
| Gap | What it means | Click-to-fix lands you at… |
|---|---|---|
toggle-off |
"Allow OpenCode sessions" is OFF in Settings | Settings → Accounts → Allow OpenCode sessions toggle |
binary-missing |
opencode CLI not found on PATH |
Settings → Accounts → OpenCode CLI binary panel |
key-missing |
No saved key for the selected model's provider | Settings → the key field for that provider (Anthropic / OpenRouter / …) |
model-unsupported |
The model id is local/unknown/malformed (v1 = hosted only) | Settings → Accounts → OpenCode model picker |
| Worktree refusal | OpenCode auto-approves every tool, so in a git repo it needs its own worktree; on the patch road (or when the worktree cannot be made) it refuses to start | The message says why in plain words — start a new session on the worktree road, or pick a hooks-based engine |
There is no virtual-project escape hatch, so the gaps apply to every OpenCode session. A resolver gap fails the turn before the server is touched (the model/key is resolved during the lazy start) with a humanized transcript line — it never sends a turn with a bad model/key.
Comparison with other providers
| Concern | OpenCode | Gemini | Anti-Gravity |
|---|---|---|---|
| Auth | Anthropic API key (env ANTHROPIC_API_KEY) |
Google API key (GEMINI_API_KEY) |
Google Sign-In (OS keyring) |
| Underlying model | Claude (Sonnet) by default; any hosted model via the picker | Gemini | Gemini / Google models |
| Streaming | Token-by-token (shared opencode serve SSE) |
Token-by-token (ACP JSON-RPC) | Block mode (full reply at end) |
| Process model | Shared persistent opencode serve server (HTTP/SSE) |
Persistent gemini --acp child |
Per-turn spawn |
| Multi-turn resume | Native (opencode ses_…, persisted in the shared DB) |
Native --resume <uuid> |
Synthesized (prepend prior turns) |
| Cost emitted | Yes — authoritative, written to api_cost_log |
No (Google-billed) | No |
| Readiness gates | 3 (toggle + binary + key) | 3 (toggle + binary + key) | 2 (toggle + binary) |
| Per-project default | No (excluded from radios — historical, not yet wired) | Yes | Yes |
| Virtual project | No | Yes (__gemini__) |
Yes (__antigravity__) |
| Session-header icon | OpenCode mark (monochrome) | Gemini bloom (gradient) | Anti-Gravity "A" (blue) |
Related
Related — gemini-provider.md
- gemini-provider.md — closest analog: token-by-token streaming (ACP JSON-RPC) + API-key auth, but Google-billed and a project-default-capable persistent provider
- antigravity-provider.md — a per-turn one-shot spawn (OpenCode is no longer one-shot — it now runs a shared persistent server), plus block-mode streaming and Google Sign-In auth
- codex-provider.md — long-lived JSON-RPC child (different process model)
- deepseek-provider.md / kimi-provider.md — also icon-badged, but Anthropic-compat API providers with no binary (reuse the
claudeCLI)
Last verified 2026-11-10