Skip to content

OpenCode

OpenCode provides a coding harness that can use several model providers, including hosted APIs, OpenCode Go, and private inference servers. You can also use Go as the model gateway behind the Claude Code harness. Choose the harness and the model separately.

Reviewed 2026-10-21 against OpenCode 2.1.0. Older examples on this wiki used V1. Start with the V2 migration guide when adapting an existing configuration; V1 plugins and server clients require migration.

Native OpenCode handles files, shell commands, web tools, MCP, sessions, and child agents. The model proposes work through those tools. Model availability does not establish tool-call reliability or coding quality: qualify the exact model, endpoint, and settings with a small read/edit/test task.

Use native OpenCode when explicit model selection and per-agent models matter. Use Claude Code with a compatible gateway when retaining Claude’s instruction loading, skills, plugins, and tool workflow matters more. The same model can behave differently in different harnesses.

ChoiceWhat it providesWhat to check
Native OpenCode + GoSubscription models and native child-agent routingWorkspace, per-model quota, task success
Claude Code + GoFamiliar Claude harness with an Anthropic-compatible Go modelProtocol support, aliases, background credentials
Native OpenCode + direct APISeparate provider accounts and model settingsMetered spend and each provider’s terms
Native OpenCode + private serverControl over model weights and serving policyHardware, tool parser, context, throughput

Install using the current official CLI instructions, then inspect the installed version and flags:

Terminal window
opencode --version
opencode run --help
opencode auth login opencode
opencode models

Select the Console workspace that owns the subscription. In the TUI, /connect manages accounts and /models selects an available model. API-key login is also available. V2 stores credentials in its database, normally ~/.local/share/opencode/opencode.db; do not publish database contents or authentication exports. See provider authentication.

Flags to know: approvals and saved sessions

Section titled “Flags to know: approvals and saved sessions”

Checked against installed OpenCode 2.1.0 on 2026-10-21:

TaskCommand
Auto-approve permission promptsopencode --auto
Continue the last sessionopencode --continue (or opencode -c)
Open a specific saved sessionopencode --session SESSION_ID (or -s SESSION_ID)
Find a saved session IDopencode session list
Continue without opening the TUIopencode run --continue "Continue the task"
Fork a saved session for another approachopencode run --session SESSION_ID --fork "Try another approach"
Choose a model and agent for a taskopencode run --model opencode-go/qwen3.7-plus --agent build "Your task"
Structured headless eventsopencode run --format json "Your task"
Check flags/versionopencode run --help; opencode --version

Combine auto-approval with continuation when intended:

Terminal window
opencode --auto --continue
opencode run --auto --session SESSION_ID "Continue the task"

--auto approves asks; explicit deny rules still apply, including the installed read-only scout/reviewer restrictions. It does not remove provider policies or disable an OS sandbox. Use an existing ID from session list: --session can also create a session if the supplied ID does not exist. A fork creates a new conversation session, not an isolated filesystem or Git worktree. --fork above belongs to run, not the top-level interactive command.

See OpenCode commands, permissions, and the cross-agent quick reference.

Global configuration lives at ~/.config/opencode/opencode.json(c). Project configuration can use opencode.json(c) or .opencode/opencode.json(c). Prefer one project form consistently; nested and system settings also participate in merging. Use the current configuration schema, not an old copied template.

{
"$schema": "https://opencode.ai/config.json",
"model": "opencode-go/qwen3.7-plus",
"warming": false,
"permissions": [
{ "action": "shell", "resource": "*", "effect": "ask" },
{ "action": "external_directory", "resource": "*", "effect": "ask" }
]
}

This model ID was present in the authenticated catalog on the review date. Use your own catalog if it changes. V2 uses providers, agents, and ordered permissions arrays; actions include shell and subagent. The last matching permission rule wins. These examples guide local tool use and do not supply OS isolation. See configuration and permissions.

Go Plus currently costs $40/month; Go costs $10/month. Allowances are model-specific, with 5-hour, weekly, and monthly windows. This is quota-limited hosted inference. Check the current Go model, pricing, endpoint, and allowance table before selecting a lane; do not convert the subscription into a claim of unlimited tokens.

For an existing subscriber, try included models before adding separate API spend. A low token price is useful only if retries, long answers, and review effort do not erase the saving. Compare cost and time per accepted change, including failed attempts.

OpenCode separates model choice from the controller that executes tools. It supports native provider integrations and compatible endpoints. A private open-weight deployment gives control over the weights, system prompt, server filters, retention, and network access. A hosted provider retains its own policies and limits.

There are three distinct controls: model response behavior, provider policy, and local tool permissions. Changing permissions or using --auto affects execution approvals; it does not remove a model’s refusal behavior. There is no universal “no guardrails” setting. For legitimate tasks that a model handles poorly, compare another suitable model or self-hosted deployment using the same acceptance checks. An endpoint that accepts chat requests still needs working tool calls for coding.

V2 discovers AGENTS.md; it does not fall back to CLAUDE.md. It supports a global ~/.config/opencode/AGENTS.md, ancestor guidance, and instructions discovered while exploring nested directories. Extra instruction files can be named explicitly:

{
"$schema": "https://opencode.ai/config.json",
"instructions": ["CLAUDE.md", "apps/wiki/CLAUDE.md"]
}

Use this only for the relevant project scope. Claude-style @file imports and .claude/rules discovery are not an OpenCode portability contract. Keep core guidance in shared AGENTS.md, and explicitly load any remaining tool-specific files. See OpenCode instructions and sharing rules, skills, and agents.

Each native agent can select its own provider/model#variant. Without a model override a child inherits its parent’s model. Children start with fresh context and use their own permissions; the parent’s subagent permission controls dispatch. This provides mixed-model orchestration, but assigning sensible roles and passing sufficient evidence remains the orchestrator’s job. See agent configuration.

The installed Mac setup uses Qwen for main work and GLM for bounded read-only roles. A small dated canary verified those native paths; it does not establish benchmark rankings. Other catalog models remain candidates for separate qualification.

RoleCandidateAcceptance condition
Installed main implementeropencode-go/qwen3.7-plusRead/edit/test canary passed; still run actual project checks
Installed scout and advisory revieweropencode-go/glm-5.3-flashBoth child sessions found the seeded defect; findings still need verification
Candidate bounded implementationopencode-go/minimax-m3Owns a disjoint change with executable checks
Candidate alternative revieweropencode-go/gpt-6-lunaFinds seeded defects and avoids false findings

For example, add a reviewer to project configuration:

{
"$schema": "https://opencode.ai/config.json",
"agents": {
"reviewer": {
"description": "Review supplied code for correctness and regressions",
"mode": "subagent",
"model": "opencode-go/glm-5.3-flash",
"permissions": [
{ "action": "*", "resource": "*", "effect": "deny" },
{ "action": "read", "resource": "*", "effect": "allow" },
{ "action": "glob", "resource": "*", "effect": "allow" },
{ "action": "external_directory", "resource": "*", "effect": "deny" },
{ "action": "read", "resource": "*.env*", "effect": "deny" }
]
}
}
}

Supply the diff and test results to this reviewer. The broad deny also blocks shell, edits, recursive dispatch, Code Mode, grep and unknown MCP actions. Grep is omitted because its permission resource is the regex, not a file path. Add the credential-path exclusions relevant to your repository; the complete maintained template has additional common exclusions. Allowed local reads are not a comprehensive secret scanner. “Read-only” in prose alone is insufficient. Markdown profiles belong in .opencode/agents/ or ~/.config/opencode/agents/. Claude profiles are not automatically imported.

Keep one integration owner. Give each worker the baseline revision, question or owned paths, relevant instructions, prohibited changes, acceptance commands, and stop conditions. Use a strong model for ambiguous planning and final decisions; trial cheaper models on bounded work with clear checks. A second model supplies leads that must be verified in code.

Start with one worker, then measure two independent tasks. Increase concurrency only when accepted throughput improves. Shared files, context duplication, provider limits, and GPU contention can make a larger team slower. Use separate worktrees for concurrent writers and inspect the integrated diff and checks. Avoid recursive delegation by default.

V2 searches .claude/skills and .agents/skills as well as OpenCode skill locations, including nested SKILL.md files. Discovery makes instructions available; it does not translate Claude tool names, plugin APIs, or frontmatter behavior. Reuse portable skill bodies and their adjacent scripts/references, then adapt tool-specific instructions. See skill discovery and IDs and the customization guide.

V2 server definitions live under mcp.servers. For a documentation server:

Terminal window
opencode mcp add context7 --url https://mcp.context7.com/mcp
opencode mcp list

Connect only the capabilities needed for the task. MCP schemas and instructions consume context, credentials remain service-specific, and an installed Claude or Codex plugin is not automatically an OpenCode plugin. See MCP setup.

V2 currently accepts LSP configuration without running LSP servers, tools, or diagnostics. The earlier V1 guide’s LSP advantage does not apply to this version. Run the project’s compiler, lint, and tests explicitly. This and other accepted-but-unsupported fields are listed in the migration reference.

These commands match installed 2.1.0 help:

Terminal window
opencode run --model opencode-go/qwen3.7-plus "Describe this project"
opencode run --format json "Explain the failing test"
opencode run --continue "Use the evidence from the previous turn"

For unattended execution, --auto approves requests that would ask; explicit denies still apply. Use it only with an appropriate execution boundary. V2 uses --server URL for a selected server and --standalone for a private server. Old --attach and --dangerously-skip-permissions examples are not current flags. See CLI commands.

Normal CLI runs use a shared background service. Environment changes in a new terminal do not necessarily reach that already-running service. A private --standalone run receives its launch environment; managed service environment is a separate configuration concern. Never put credential values in command arguments. See CLI architecture.

Capture structured events, stderr, usage, model identity, termination reason, and resulting artifacts privately. Verify the actual diff and tests. A model-written PASS or exit zero alone is insufficient.

The operator Mac now has a small global AGENTS.md, explicit native Go models, warming disabled, read-only scout/reviewer profiles, and five maintained shared skills. Three installed skill files had contained only NUL bytes; those were backed up and rebuilt. The other two were refreshed to correct old flags, hosted-quota assumptions and overstated reliability guidance. Claude rule and hook files, credentials and managed synced skills were preserved.

The versioned dotfiles setup provides a scoped installer with private backups plus oc-task for bounded native runs. Inspect its personal configuration before applying it elsewhere. The launcher aligns cwd and PWD, closes stdin, uses a private server, terminates its process group on deadline, retains partial work and selected usage metadata, and never retries automatically. Exit zero requires a passing explicit checker plus normal completion and expected model metadata; without a checker it reports unchecked work with exit 2. Its checker runs trusted local code and is not a generated-code sandbox.

A native Qwen read/edit/test fixture passed in 16.4 seconds with its test file unchanged. A Qwen parent then launched GLM scout and reviewer sessions; both identified the seeded subtraction regression with unchanged fixture files. The runtime permission evaluator passed positive read/glob controls and negative tool/resource controls for both actual children. The refreshed reliability skill also loaded through the native tool and correctly rejected a missing-file DONE claim. See the dated receipt for exact evidence and limits.

These are small daily-configuration canaries, separate from the 81-attempt benchmark. They do not qualify repository-scale autonomous work, credential renewal, compaction or the separately blocked Proxmox model controller.

Use a provider matching your server’s protocol. A minimal V2 example is:

{
"$schema": "https://opencode.ai/config.json",
"model": "private/coder",
"providers": {
"private": {
"name": "Private inference",
"env": ["PRIVATE_INFERENCE_API_KEY"],
"package": "@opencode/ai/providers/openai-compatible",
"settings": { "baseURL": "http://127.0.0.1:8000/v1" },
"models": { "coder": {} }
}
}
}

Replace coder with the exact served model ID. Add verified capabilities and context/output limits from the deployed model and server; unknown-model defaults are not hardware detection. Discovery cannot infer vLLM’s tool-call parser flags. Test streamed tool calls, edits, and failure recovery before repository use. See provider configuration and offline model qualification.

Claude Code + OpenCode Orchestration (Best of Both Worlds)

Section titled “Claude Code + OpenCode Orchestration (Best of Both Worlds)”

There are two useful arrangements. Claude Code can dispatch separate native OpenCode workers, each with an explicit model and narrow contract. Alternatively, Claude Code itself can use the Go Anthropic-compatible gateway:

Claude Code tools, rules, skills, plugins
→ Go Anthropic endpoint
→ compatible selected model

The gateway endpoint is https://opencode.ai/inference/go/anthropic. Use a model listed with that protocol, such as the locally verified qwen3.7-plus; native OpenCode’s broader catalog does not imply every model works with Claude’s protocol. Go recognizes Claude Code’s native session header, so a header-spoofing wrapper is unnecessary. See Go endpoints and the Claude gateway setup.

The local cc-opencode launcher preserves the Claude harness. Native OpenCode agents configuration does not control Claude child agents. Its initial aliases deliberately use one verified model; mixed-model Claude children require their own compatible model mapping and qualification.

Prompt caching reuses a matching rendered prefix. Keep system guidance and tool definitions stable, load large skills on demand, and append changing task material later. Reusing a conversation helps; repeatedly switching models, endpoints, tool catalogs, or instruction files can lose reuse. Cache hits and discounts depend on the actual provider, not a universal OpenCode switch. See OpenAI caching and Anthropic caching.

OpenCode adds cache markers for supported routes. An Anthropic model behind an OpenAI-compatible proxy may need model compatibility.cacheFormat: "anthropic"; do not apply this blindly to other models or endpoints. Check actual usage rather than assuming the proxy honors it. See OpenCode model compatibility.

MechanismWhat it savesWhat it does not promise
Provider prompt cacheRepeated prefix processing and eligible input chargesFree output or cross-model reuse
Self-hosted vLLM prefix cachePrefill computation for shared prefixesFaster decoding of new output tokens
Conversation compactionContext space using a summary or supported checkpointLossless recollection or a separate cheap summarizer
Session warmingMay retain short-lived provider stateA free cache refresh

vLLM prefix caching is a serving feature. Measure prefill latency, cache occupancy, and accepted jobs per hour; hardware and concurrency still cost resources.

OpenCode compaction uses the session model and retains about 15,000 recent tokens by default. Summaries are lossy; supported encrypted checkpoints are tied to their provider/model/endpoint. Keep durable requirements and exact results in project artifacts rather than trusting a summary alone.

Warming is off by default. Enabling it sends real inference requests every four idle minutes for up to 30 minutes after normal activity. Those calls consume spend or quota. Leave it off until measurements show a net benefit.

Record uncached input, cache writes, cache reads, output, retries, warming, wall time, and acceptance/rework rate. Provider counters differ: Mistral includes cached tokens within prompt tokens, while Anthropic exposes separate input/cache categories. Avoid double-counting. Several agents can reuse eligible common prefixes, but each still incurs its own task and output usage.

  • Check the installed major version before copying a tutorial. Accepted legacy config can still contain ignored fields.
  • Keep provider identity, account/workspace, exact model, and protocol explicit. A non-Anthropic URL may be a metered hosted gateway.
  • A healthy server, catalog entry, or successful text reply does not qualify an autonomous coding worker.
  • A worktree separates Git changes; tool permissions, credentials, and execution isolation determine access.

See the study audit and current OpenCode tests for independently scored Go fixtures, confidence intervals, the inherited-PWD launcher issue, and corrections to the June homelab paper. Keep native OpenCode qualification separate from the earlier Claude-harness gateway canary; each uses its own tool loop and settings.

Recent changes

  1. docs(wiki): add coding agent approval and session flag references @sac
  2. docs(wiki): publish installed OpenCode workflow and validation @sac
  3. docs(wiki): audit reliability study and record OpenCode qualification @sac
  4. docs(wiki): add source-checked OpenCode community workflows @sac
  5. docs(wiki): refresh OpenCode V2 orchestration and shared customization @sac