Omniscio

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 serve server'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.compacted event, 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 opencode CLI for you (npm opencode-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 by provider-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-key Settings-search anchors landable; a saved key is preserved.

  1. 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).
  2. OpenCode CLI binary — the opencode binary must be on your PATH. The Set it up for me button installs it for you (npm opencode-ai, bin opencode) 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, run npm install -g opencode-ai. Omniscio speaks OpenCode 1. The npm opencode-ai package only ever carries OpenCode 1 (OpenCode 2 ships separately as @opencode/cli), but Homebrew's opencode formula is OpenCode 2, so Omniscio never updates OpenCode through Homebrew. The resolver also discovers an npm-global install via npm root -g, so a GUI-launched Omniscio with a narrow PATH still finds it. (OpenCode is registered in Omniscio's toolchain installer with defaultSelected:false — installable on demand, never auto-installed in the first-run "install recommended tools" sweep.)
  3. 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 from PROVIDER_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)
  • 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 claude CLI)

Last verified 2026-11-10