OpenCode
OpenCode
Section titled “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.
What is OpenCode?
Section titled “What is OpenCode?”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.
Why OpenCode? (vs. Alternatives)
Section titled “Why OpenCode? (vs. Alternatives)”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.
| Choice | What it provides | What to check |
|---|---|---|
| Native OpenCode + Go | Subscription models and native child-agent routing | Workspace, per-model quota, task success |
| Claude Code + Go | Familiar Claude harness with an Anthropic-compatible Go model | Protocol support, aliases, background credentials |
| Native OpenCode + direct API | Separate provider accounts and model settings | Metered spend and each provider’s terms |
| Native OpenCode + private server | Control over model weights and serving policy | Hardware, tool parser, context, throughput |
Installation
Section titled “Installation”Install using the current official CLI instructions, then inspect the installed version and flags:
opencode --versionopencode run --helpopencode auth login opencodeopencode modelsSelect 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:
| Task | Command |
|---|---|
| Auto-approve permission prompts | opencode --auto |
| Continue the last session | opencode --continue (or opencode -c) |
| Open a specific saved session | opencode --session SESSION_ID (or -s SESSION_ID) |
| Find a saved session ID | opencode session list |
| Continue without opening the TUI | opencode run --continue "Continue the task" |
| Fork a saved session for another approach | opencode run --session SESSION_ID --fork "Try another approach" |
| Choose a model and agent for a task | opencode run --model opencode-go/qwen3.7-plus --agent build "Your task" |
| Structured headless events | opencode run --format json "Your task" |
| Check flags/version | opencode run --help; opencode --version |
Combine auto-approval with continuation when intended:
opencode --auto --continueopencode 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.
Configuration
Section titled “Configuration”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 and cheaper model access
Section titled “Go Plus and cheaper model access”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.
Many models and fewer restrictions
Section titled “Many models and fewer restrictions”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.
Custom Instructions (AGENTS.md)
Section titled “Custom Instructions (AGENTS.md)”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.
Custom Agents
Section titled “Custom 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.
| Role | Candidate | Acceptance condition |
|---|---|---|
| Installed main implementer | opencode-go/qwen3.7-plus | Read/edit/test canary passed; still run actual project checks |
| Installed scout and advisory reviewer | opencode-go/glm-5.3-flash | Both child sessions found the seeded defect; findings still need verification |
| Candidate bounded implementation | opencode-go/minimax-m3 | Owns a disjoint change with executable checks |
| Candidate alternative reviewer | opencode-go/gpt-6-luna | Finds 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.
Getting stronger results
Section titled “Getting stronger results”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.
Skills
Section titled “Skills”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.
MCP Servers
Section titled “MCP Servers”V2 server definitions live under mcp.servers. For a documentation server:
opencode mcp add context7 --url https://mcp.context7.com/mcpopencode mcp listConnect 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.
LSP Integration
Section titled “LSP Integration”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.
Headless Mode & Automation
Section titled “Headless Mode & Automation”These commands match installed 2.1.0 help:
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.
Installed local workflow (2026-10-21)
Section titled “Installed local workflow (2026-10-21)”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.
Self-Hosted Backend (vLLM)
Section titled “Self-Hosted Backend (vLLM)”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 modelThe 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.
Caching, compaction, and cost
Section titled “Caching, compaction, and cost”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.
| Mechanism | What it saves | What it does not promise |
|---|---|---|
| Provider prompt cache | Repeated prefix processing and eligible input charges | Free output or cross-model reuse |
| Self-hosted vLLM prefix cache | Prefill computation for shared prefixes | Faster decoding of new output tokens |
| Conversation compaction | Context space using a summary or supported checkpoint | Lossless recollection or a separate cheap summarizer |
| Session warming | May retain short-lived provider state | A 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.
Tips & Known Issues
Section titled “Tips & Known Issues”- 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.
Measured local qualification
Section titled “Measured local qualification”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.