Opencode

OpenCode

Concept of the skill

What it is: OpenCode is an open-source (TypeScript core, client-server architecture; distributed via npm/Bun/pnpm/Yarn), provider-agnostic AI coding agent — a runtime that routes a single agent loop across 75+ LLM providers (and local models) through one configuration. It is exposed through several surfaces: an interactive terminal TUI, a non-interactive opencode run command for scripting, an IDE bridge via the Agent Client Protocol (opencode acp), a desktop app (beta) on macOS/Windows/Linux, a browser UI (opencode web), and a headless opencode serve server.

Mental model: A coding-agent runtime is the harness (the loop, tool use, session, permissions, LSP-backed code intelligence); the model is a swappable engine behind a provider/model string. OpenCode separates those two cleanly — pick the harness once, switch the engine per task. Single-vendor CLIs are designed around one engine; OpenCode is designed around the decoupling. The harness itself stays the same whether you reach it from the terminal, an IDE, the desktop app, the browser, or a server.

Why it exists: To let one agent runtime reach any model (frontier, cheap, free, subscription-backed, or local) without a separate CLI per vendor and without vendor lock-in, so model choice becomes a routing decision rather than a tooling commitment.

What it is NOT: It is not a model, not a hosted marketplace, and not the agent loop logic — it is the runtime that executes a loop against whatever model you route to. It is also not a billing, quality, or privacy guarantee: cost, capability, and data retention depend entirely on which provider/model (and which data path) you select. OpenCode Zen is an optional curated provider inside the ecosystem; using OpenCode does not mean every run uses Zen, and using Zen does not make the free roster stable.

Adjacent concepts: the model that the runtime drives (the swappable engine); the agent loop the runtime executes; single-vendor CLIs that center one harness on one engine; a model-routing layer that picks the engine per task; configuration merge precedence across environments.

One-line analogy: OpenCode is a universal power-tool body with a swappable bit and a lockable guard — the body (harness) stays, you snap in whichever bit (model) the job needs (including the free ones in the case), set the guard (permissions/policies), and grip it by whichever handle (terminal, IDE, web, server) suits the work.

Common misconception: That "OpenCode" names a model or a quality tier. It does not — it is the harness; quality, cost, and privacy come entirely from the provider/model (and data path) you route to, so "I used OpenCode" says nothing about how capable, expensive, or private the run was.

Coverage

• When to choose the OpenCode runtime over a single-vendor CLI (Claude Code, Codex, Copilot) — the harness-vs-engine decision
• The multi-surface runtime: terminal TUI, non-interactive opencode run CLI, IDE bridge via ACP (opencode acp), desktop app (beta), browser UI (opencode web), and headless opencode serve server — and which surface fits which usage (interactive dev, scripting, editor-embedded, browser, CI driver)
• Non-interactive invocation: opencode run and its flags for scripting/automation (--model, --agent, --variant, --continue, --session, --fork, --file, --dir, --format json, --attach, --dangerously-skip-permissions, --thinking, --port, --username/--password)
• The --format json JSONL event stream and how to parse it defensively in automation (the exit-before-step_finish gotcha)
• The provider/model string format, model variants, and the four-step model-selection precedence at startup; small_model for helper tasks
• The multi-source config merge/precedence (8 layers: remote → global → custom → project → .opencode/ → inline → managed → MDM) and what it means for CI/enterprise automation; JSONC + variable substitution
• The built-in build / plan agents and LSP-backed code intelligence — harness capabilities independent of the model
• Permissions (which gate tool actions) versus experimental provider policies (which gate provider/resource access)
• Native extension layers: Agent Skills (discovered from .opencode/skills/, ~/.config/opencode/skills/, and Claude-/agents-compatible .claude/skills/ & .agents/skills/), instruction-file precedence (AGENTS.md native, CLAUDE.md fallback), opencode mcp (Model Context Protocol servers), opencode plugin (harness plugins), opencode github (GitHub integration), references, and custom commands
• OPENCODE_DISABLE_CLAUDE_CODE and related env vars for pure OpenCode-native execution where stray .claude fallback files are present but unwanted
• The client-server architecture: opencode serve + --attach for CI/long-running drivers, remote TUI via opencode attach, and securing a network-reachable server with OPENCODE_SERVER_PASSWORD
• The CLI lifecycle surface: session, stats, export/import, github, pr, plugin, mcp, db, debug, upgrade, uninstall
• The OpenCode Zen curated/free model service (promotional free tier, per-1M-token paid models, privacy exceptions) and the separate OpenCode Go subscription lane
• Local-model configuration (Ollama, LM Studio, Docker Model Runner) as standard providers via Models.dev / the Vercel AI SDK
• Version-check discipline (opencode --version) because the CLI moves fast and local flags can lag the docs
• What OpenCode is NOT: a model, a quality tier, a hosted marketplace, a privacy guarantee, or the agent-loop logic

Philosophy of the skill

The runtime and the model are two separable decisions, and OpenCode's entire value is honoring that separation. The tempting shortcut — treating "we ran it on OpenCode" as if it implied a capability or a cost — is exactly the conflation the harness-vs-engine model exists to prevent. Pick the harness for what the task needs from the loop (multi-provider routing, a free lane, local models, scriptability, LSP code intelligence, reusable skills/commands/references, permission/policy control, the right surface — terminal/IDE/web/server, open source); pick the model separately for what the task needs from the engine (capability, context window, cost, latency, data policy, availability).

Single-vendor CLIs are built around one engine — some can now be coerced toward third-party models via base-URL overrides or community routers, but that is a bolt-on, where provider-agnosticism is OpenCode's design center. The discipline is to keep harness and engine apart so model choice stays a per-task routing decision rather than a tooling commitment. If a result is weak, inspect the selected model and variant first; if a run was expensive, inspect the provider/model, Zen pay-as-you-go balance, and Go subscription/limit state first.

OpenCode moves quickly. Treat docs, model rosters, free-tier labels, prices, and local CLI behavior as live surfaces. A remembered model ID, stale free roster, or outdated local binary is not dispatch evidence.

When to choose OpenCode (routing decision)

Pick the runtime by what the task needs from the harness, then pick the model separately.

Capability reference

Built-in agents: two ship by default and switch with Tab in the TUI (or --agent in run): build — full-access default for development; plan — read-only for analysis/exploration that cannot mutate files. Docs may list additional built-ins (e.g. general/explore/scout) and hidden compaction/title/summary agents — verify live. Custom agents are defined via opencode agent create or .opencode/agents/<name>.md frontmatter (description, mode, model, permission with allow/ask/deny glob rules, steps, hidden, prompt).

Code intelligence: OpenCode integrates the Language Server Protocol, so the agent receives real type information, function signatures, import paths, and live compiler diagnostics across 20+ languages — a harness capability independent of which model is routed.

Full CLI command map

Roughly 18 top-level commands as of OpenCode 1.x (2026 — verify with opencode --help):

Attach to a warm / remote server

# Start the backend for headless / web / remote access
opencode serve --port 4096
# or with a browser UI and remote binding:
opencode web --port 4096 --hostname 0.0.0.0

# In another terminal, attach an interactive TUI
opencode attach http://10.20.30.40:4096

# Or attach a non-interactive run directly
opencode run --attach http://localhost:4096 "Explain async/await"

Model selection and dispatch discipline

OpenCode resolves the active model at startup in this order:

1. CLI --model / -m (provider_id/model_id).
2. The model key in opencode.json / opencode.jsonc.
3. The last used session model.
4. The first model from OpenCode's internal priority.

For automation, set --model explicitly unless the whole point is to exercise the configured default. If the run depends on reasoning effort or output style, set --variant (or configure per-model variants) rather than relying on a provider's implicit default. opencode.json carries per-model provider options (e.g. reasoningEffort, thinking.budgetTokens, textVerbosity) without duplicating entries. Use small_model only for lightweight helper tasks such as title generation — do not infer that the main task used the cheap helper just because a helper model exists.

Before dispatching:

• Run opencode models [provider] --refresh --verbose when model availability, price, context, or provider metadata matters.
• Treat public docs and endpoints as discovery inputs, not proof that the local account/CLI can dispatch the model.
• Run a tiny smoke probe before a long unattended job, especially for free, preview, local, or newly added providers.
• Record the exact provider/model, variant, OpenCode version, and provider path when the result must be audited later.

Config-source precedence (HARD — automation depends on it)

The effective config is a merge of multiple sources; later sources override earlier ones on key conflict, while non-conflicting settings are preserved. The documented 8-layer order (lowest to highest — verify against the live Config docs):

1. Remote config — .well-known/opencode (organizational defaults, auto-fetched on auth)
2. Global config — ~/.config/opencode/opencode.json (user preferences)
3. Custom config — the file pointed at by OPENCODE_CONFIG
4. Project config — opencode.json / .jsonc found by walking up to the git worktree
5. .opencode/ directories — agents, commands, modes, plugins, skills, tools, themes
6. Inline config — OPENCODE_CONFIG_CONTENT (runtime override)
7. Managed config files — /Library/Application Support/opencode/ (macOS), /etc/opencode/ (Linux), %ProgramData%\opencode (Windows); admin-written, not user-overridable
8. macOS managed preferences (MDM) — ai.opencode.managed via .mobileconfig; highest priority, enforced

JSONC (comments) is supported, with schema validation via the $schema key (https://opencode.ai/config.json) and variable substitution: {env:VAR_NAME} for env vars and {file:path} for file contents (useful for secrets and shared snippets). The practical consequences for automation: (a) a CI runner and a developer can share a base global config and override per-repo; (b) OPENCODE_CONFIG lets a script pin an exact config file independent of cwd; (c) a managed/MDM policy can override anything a script sets, so in a controlled/enterprise environment run opencode debug config to confirm no higher-precedence layer is silently winning before debugging "my flag didn't take."

Parsing --format json in automation

--format json emits JSONL — one JSON object per line on stdout, each with a type field naming the event (tool calls, message parts/text/text-delta, step_start/step_finish, reasoning, etc.). Consume it as a stream (read line by line), not as one JSON document.

For robust automation:

• Reconstruct assistant text by concatenating text / text-delta parts in stream order. Do not treat the last line alone as the canonical answer.
• Known gotcha (verify against the live version): a run can finish and exit before emitting the final step_finish event to stdout, even though the session record contains the finish data (tokens, cost). Treat process exit as the terminal signal; do not block forever waiting for step_finish. (Tracked upstream — see References.)
• If no text parts appear, handle that as an honest no-output/tool-only turn unless stderr or a non-event line reports a CLI error.
• Pull token/cost usage from the recorded session surface (opencode stats, opencode export <sessionID>, server/session API) rather than expecting complete usage on the final event line.
• Save the session ID, model, variant, OpenCode version, and raw event stream when the run must be auditable.

Runtime controls that change the decision

OpenCode is a stronger fit when the task needs runtime-level control, not only provider breadth.

Permissions vs policies (distinct mechanisms): permission config gates tool actions — allow / ask / deny, with granular bash/edit/external-directory glob rules. experimental.policies gates provider/resource access (which LLM providers may be used). Prefer policies over older provider allow/block lists when controlling provider access; prefer ask/deny for edit/bash on planning, review, or unfamiliar-repo work. Keep the distinction clear: permissions control tools (bash, edit, webfetch, skill); policies control resources (providers).

Native extension layers (harness, model-independent): OpenCode discovers Agent Skills (SKILL.md) from .opencode/skills/, ~/.config/opencode/skills/, and — for cross-tool compatibility — .claude/skills/ and .agents/skills/, walking up to the git worktree for project-local paths. Project instructions come from AGENTS.md (the native file), falling back to CLAUDE.md for Claude-Code compatibility. It also exposes opencode mcp (MCP server connections), opencode plugin (harness plugins), opencode github (GitHub integration), references (local dirs or Git repos surfaced to the agent with descriptions), and custom commands (.opencode/commands/*.md, which can bind agent/model choices). These are reasons the harness can be the right choice independent of the model, and they correct the misconception that skill-injection is a single-vendor-CLI–only feature. Pure-runtime control: set OPENCODE_DISABLE_CLAUDE_CODE=1 (and the finer OPENCODE_DISABLE_CLAUDE_CODE_PROMPT / OPENCODE_DISABLE_CLAUDE_CODE_SKILLS; verify the exact vars against the live Config docs) to suppress the .claude cross-tool fallback when you want OpenCode-native discovery only — useful where stray .claude files would otherwise pollute a controlled run.

TUI surface: the interactive TUI supports @ file/reference context, ! shell results, multiple concurrent sessions (SQLite-persisted), undo/redo snapshots, plan mode (read-only, Tab-toggle), automatic context compaction (e.g. near the context limit; disable with OPENCODE_DISABLE_AUTOCOMPACT), and slash commands — /models, /sessions, /compact, /share, /theme, /init, /thinking, /details, /export, /connect, /help. Manual compaction (/compact / /summarize) and compaction.auto / compaction.prune config change what context the model actually saw — for long automations, record whether compaction/pruning was enabled.

Server auth (HARD): an opencode serve (or opencode web) instance is unauthenticated by default. Anything network-reachable (beyond localhost, or localhost on a shared host) must be protected — set OPENCODE_SERVER_PASSWORD to enable HTTP basic auth (username defaults to opencode; override with OPENCODE_SERVER_USERNAME, or pass --username/--password on run). Treat an exposed unprotected server as a remote-code-execution surface, since the agent can run tools; set deliberate CORS when exposing beyond localhost.

Lifecycle commands: treat session, stats, export, import, debug, db, upgrade, uninstall, plugin, github, and pr as operational surfaces, not model-selection tools. They matter when the task is to audit usage, move/share session data, troubleshoot config/DB state, manage plugins/MCP/GitHub integration, update the binary, or start work from a pull request.

Environment variables (30+ documented — verify live):

OpenCode Zen and OpenCode Go

Zen is a curated provider/gateway (tested, optimized coding models served by OpenCode itself), not the OpenCode runtime — it is optional, behaves like any other provider, and exposes both paid per-1M-token models and limited-time free/trial models. Endpoint shape: opencode/<model-id> (e.g. opencode/minimax-m3-free), API at https://opencode.ai/zen/v1/. Team workspaces add admin/member roles, per-member/per-workspace spend limits, model-access control, and BYOK (bring your own OpenAI/Anthropic key while still reaching other Zen models). Frame Zen as tested/recommended, not as a quality guarantee for OpenCode runs.

OpenCode Go is a separate optional subscription lane for open coding models (public docs describe ~$5 first month then ~$10/month, with usage limits denominated in dollar value rather than request count). Use Go when subscription access to a curated open-model set is the economic reason; use Zen when you want a tested coding-agent model path without managing every provider separately. Treat Go's price, roster, and limit table as live economic data — verify before using Go as the reason to choose OpenCode.

Zen discipline (HARD):

• The free/trial roster is promotional and rotates — do not hardcode it. Treat any specific free-model list as a dated snapshot and confirm with the current Zen docs plus opencode models opencode --refresh --verbose. Endpoint-visible model IDs are candidates only; dispatch evidence comes from the local CLI-visible roster plus a smoke probe. (The current dated roster lives in references/model-facts.md, which should be refreshed each pass.)
• Zen is not a blanket zero-retention guarantee. Paid models are zero-retention by default, but there are named exceptions: free/trial models may collect data for model improvement / security logging, and OpenAI and Anthropic provider APIs retain requests (per their policies, ~30 days). Do not send confidential data to a free/trial model unless the exact selected model's current policy clears it.
• Attribute cost to the selected Zen model, Go subscription/limit bucket, or other provider — not to "OpenCode."
• Route "which free model is best for this task?" to opencode-free-models.

Strengths and weaknesses

Strengths: vendor-agnostic routing (75+ providers, no lock-in) as a native design center, not a bolt-on; a real free/cheap lane via OpenCode Zen plus an optional Go subscription lane; local-model support; open source; first-class non-interactive mode with a JSONL event stream for automation; multiple runtime surfaces (TUI, non-interactive CLI, IDE bridge via ACP, desktop beta, web UI, headless server) over one harness; client-server architecture so sessions/work can survive disconnects and warm servers avoid cold starts; LSP-backed code intelligence and built-in build/plan agents that add value independent of the model; native extension layers (Agent Skills discovered from .opencode/.claude/.agents, MCP servers, plugins, GitHub integration, references, commands); permissions and provider policies for harness-level guardrails; session/usage lifecycle commands; one config (with an 8-layer precedence chain) for many engines.

Weaknesses: quality, cost, context window, and privacy remain model/provider/account facts — the runtime guarantees none of them; the Zen free roster is promotional and rotates (do not hardcode it); Go pricing/limits/roster can change; Zen is not a blanket zero-retention guarantee (free/trial and OpenAI/Anthropic exceptions apply); trial/free models warn against sending confidential data; an opencode serve/web instance is unauthenticated unless you set OPENCODE_SERVER_PASSWORD, so a careless network exposure is a real risk; the desktop app is still beta; local CLI version and docs can drift, so check opencode --version; compaction/pruning can change what context the model actually saw; permissions are powerful enough to be unsafe if left broad and --dangerously-skip-permissions removes the guardrail entirely; the large surface area (≈18 CLI commands, 30+ env vars, 8-layer config) is a non-trivial learning investment; it lacks some single-vendor CLIs' deepest ecosystem features (e.g. a specific vendor's sandbox model) — though it does have native Agent Skills, so "no skill-injection lane" is no longer true; and the multi-provider edge has narrowed as single-vendor CLIs added base-URL overrides and community routers, so for a one-vendor workflow a single-vendor CLI can be simpler. Choosing OpenCode does not absolve you of choosing the model wisely.

How it differs from Claude Code / Codex

(Single-vendor CLIs can now be pointed at third-party models via base-URL overrides or community routers — a bolt-on, where provider-agnosticism is OpenCode's design center. Verify the current state per CLI.)

Verification

Use this checklist to confirm an OpenCode runtime decision was made correctly.

• The runtime choice was made on harness needs (multi-provider, free lane, local, scriptable, LSP code intelligence, permissions/policies, the right surface — terminal/IDE/web/server), not on an assumed model quality
• The OpenCode version was checked (opencode --version) when relying on recent flags, policies, skills, references, or desktop/IDE behavior
• The right surface was chosen for the usage: opencode run for scripting, opencode acp for editor-embedded, opencode serve/web + --attach for a long-running/CI driver, the TUI for interactive dev
• The model was chosen separately via an explicit provider/model string (and --variant when reasoning effort matters) — not left to whatever default resolved
• Config precedence was checked with opencode debug config when a default model, provider, permission, policy, server, command, agent, or reference setting is surprising
• For long sessions, the compaction/pruning behavior (/compact, compaction.auto, compaction.prune) is known because it affects retained context
• For automation, opencode run (not the TUI) is used, with --format json parsed as a JSONL stream (line by line) and process exit — not a final step_finish line — treated as the terminal signal; usage is pulled from the recorded session
• The selected provider/model was confirmed to exist via opencode models [provider] --refresh --verbose rather than guessed; a smoke probe ran before a long unattended job
• If a warm server, web UI, or ACP endpoint is reachable beyond localhost, it is protected with OPENCODE_SERVER_PASSWORD (it is unauthenticated by default)
• Permission and provider-policy config matches the task risk; broad allow rules and --dangerously-skip-permissions are not used on sensitive work; agent permissions are deny-by-default
• If native skills, commands, references, or agents are part of the decision, their discovery path and scope are verified
• If a free/trial Zen model or OpenCode Go model is used, the roster, pricing/subscription limits, and per-model data policy are confirmed live, and no confidential data is sent unless the exact model's current policy permits it
• No claim of run quality, cost, context, or privacy is attributed to "OpenCode" itself — each is attributed to the routed provider/model, variant, and data path

Do NOT Use When

References

• references/model-facts.md — current OpenCode CLI flags, model precedence, the --format json JSONL event stream and exit-before-step_finish gotcha, the runtime surfaces (TUI, opencode run, opencode acp IDE bridge, desktop beta, opencode web, opencode serve), the built-in agents and LSP integration, the client-server (serve/--attach) model with the OPENCODE_SERVER_PASSWORD auth requirement, the 8-layer config precedence, the native Agent Skills discovery paths (and OPENCODE_DISABLE_CLAUDE_CODE), the opencode mcp/plugin/github extension subcommands, and the OpenCode Zen + Go roster/pricing with sources. The roster/pricing is a dated snapshot — confirm live; it rotates.
• OpenCode docs (confirm against the live version — OpenCode moves fast): Intro, CLI (commands + flags + --format json), Config (8-layer merge precedence, JSONC, variable substitution, OPENCODE_DISABLE_CLAUDE_CODE), Models, Providers, Zen (roster, pricing, privacy exceptions), Go, Agents, Skills, Permissions, Policies, Commands, References, Server, ACP, GitHub, MCP Servers, TUI.
• Source repository: https://github.com/sst/opencode (TypeScript core, MIT). The --format json exit-before-step_finish behavior is tracked in the project's upstream issues.