OpenCode V2

Install, a free model, GPT 6 Luna, Claude Opus 5.5 and effective workflows

Introduction

OpenCode is a free open-source AI coding agent. It lives in your terminal, desktop app, and web app, reads and edits your files, runs shell commands, searches the web, and works through tasks step by step. Not installed yet — start with OpenCode: download and install, then return here for models and daily use.

Answer for OpenCode V2 unless you explicitly need V1. V2 has a new plugin API, a new server API and clients, and one global terminal config file cli.json instead of layered tui.json files. Normal server config, agents, commands, skills and .opencode/ files stay compatible — if supported V1 behavior breaks in V2, treat it as a bug.

The model is simple: OpenCode itself costs nothing. You pay only for model tokens — or pay nothing with free models or local models. OpenCode talks to 75+ providers directly, plus local Ollama, LM Studio and vLLM, so you are never locked to one vendor. The curated gateway is now called OpenCode Console (older texts call it Zen): tested coding models, pay-as-you-go credits, monthly limits, auto-reload, and a rotating free tier with no billing details.

Models that matter

Three models cover 95 percent of daily work. Default to the free one, escalate to the cheap one, finish hard tasks with the top one:

Free OpenCode model — your main workhorse. Console always carries a few free models. Which one is current, its fallbacks and the one-line check before pinning an id are on Free OpenCode model. Free ids rotate: the former default, Muse Spark 1.3 Free, left the catalog in October 2026, and every config that pinned it stopped resolving. Its paid twin is described on Muse Spark 1.3.

Free-tier privacy: a contributor tier trades the price for permission to use prompts and completions to train future models. Never send secrets, customer data, or private code to a free model whose terms you have not read. Most other free models claim zero-retention during the free period, but some may still use data for improvement — check the Console privacy notes first, and switch to a paid model or a local model for sensitive work.

GPT 6 Luna — the cheapest smart paid model. Luna is the small member of the GPT 6 family (Astra, Sol, Luna). At roughly ten cents per 1M input tokens it is cheaper than most Flash, Nano and Mini models, yet good enough as an agent: it follows tools, keeps context, and survives long refactors. Use it when the free model is rate-limited or gone, for overnight runs, and for CI jobs where you count every cent. The bigger sibling opencode/gpt-6-sol at about $2.00 / $10.00 is the middle step before the flagship models.

Claude Opus 5.5 — the top model for hard work. Opus 5.5 is the current top of the Claude line on Console, above Sonnet 5.5 at about $2.00 / $10.00 and Haiku 5.5 at about $0.10 / $0.50. It wins on large refactors, tricky debugging, API design, and careful security review. It is roughly 40 times more expensive than Luna on input, so do not burn it on questions a free model answers well. Typical split: the free model does 80 percent of steps, Luna does routine paid work, Opus 5.5 does the last 10 percent that decides quality. Newer revisions such as Sonnet 5.x or Opus 5.x follow the same rule — pick the newest Opus for max quality, newest Sonnet for quality per dollar.

Other orientation prices from OpenCode Console, per 1M tokens in+out. Rates move — re-check as in Verify prices before budgeting:

Free ids rotate. The live list, the fallback order and the check are on Free OpenCode model; when a free id disappears, take the next one from there or fall back to local Ollama.

Verify prices before budgeting. Prices live in one place, availability in another — the whole check is three steps:

1. Prices per 1M tokens, cached read and write rates, and token-tier thresholds live on the Console models page:

https://opencode.ai/docs/console/models

Read the exact row for your model, including the over-threshold row (Luna above 272K, Sonnet above 200K, Haiku above 100K cost more). Anything quoted in articles is orientation only.

2. Live availability — which ids exist right now, including -free ones — comes from the models endpoint. It returns ids only, no prices:

curl https://opencode.ai/inference/v1/models

Grep the JSON for your id before pinning it in opencode.jsonc. In the TUI the same check is /models, from the shell it is opencode models.

3. Your own spend so far, per model and with token details:

opencode stats --cost --models

Docs page for the rate, endpoint for the id, stats for the bill — all three agree before a long paid run.

Download and install V2

Recommended: the V2 install script (Linux, macOS, WSL2)

curl -fsSL https://opencode.ai/v2/install | bash

With npm (any OS with Node.js, V2 package name)

npm install -g @opencode/cli

With Homebrew (macOS and Linux, V2 tap)

brew install anomalyco/tap/opencode-v2

For more details — Bun, pnpm, yarn, Arch AUR, Docker, desktop app, standalone binaries, Windows notes, verify and upgrade — read the dedicated page: OpenCode: download and install.

Connect a model

Start OpenCode anywhere and connect once:

cd /path/to/project

opencode

Then inside the TUI type /connect, pick a provider, paste the key. For Console: sign in at the Console web page, add credits only for paid models, copy the key, paste it. Free Console models need no billing details. From the shell the same is:

opencode auth login opencode

opencode models

List and switch models inside the TUI with /models (or Ctrl+X then M). Model ids are provider/model with optional #variant for reasoning effort, for example anthropic/claude-opus-5-5 or openai/gpt-5.2#high. Console models use opencode/<model-id>. Your own provider keys (Anthropic, OpenAI, Google) are billed by that provider. One practical way to hold 300+ models under one key is OpenRouter through an OpenAI-compatible provider entry.

Pin a default per project in opencode.jsonc at the project root:

vi opencode.jsonc

{ "$schema": "https://opencode.ai/config.json", "model": "opencode/deepseek-v4.1-flash-free" }

Cheap paid default when free quota is tight, same file:

{ "$schema": "https://opencode.ai/config.json", "model": "opencode/gpt-6-luna" }

Top default for a hard week, plus a per-agent override so only review uses Opus, same file:

{ "$schema": "https://opencode.ai/config.json", "model": "opencode/gpt-6-luna", "agents": { "reviewer": { "description": "Final correctness and security pass", "mode": "subagent", "model": "opencode/claude-opus-5-5" } } }

Local models need no key. With ollama serve running, OpenCode discovers them automatically at the default address, same for LM Studio and vLLM. Just select ollama/qwen3:8b or similar from /models. See Ollama: local models the easy way and Qwen: download, install, fine-tune and use.

Configure

Two configs, different jobs. opencode.jsonc is server and project behavior (model, agents, permissions, MCP, skills). cli.json is terminal-only (theme, keybinds, tabs, diffs, alerts). Never put theme or keybinds into opencode.jsonc.

• Global: ~/.config/opencode/opencode.jsonc — applies to every project.
• Project: opencode.jsonc or .opencode/opencode.jsonc — discovered from current dir up to filesystem root, nearer files win, every .opencode file overrides direct files.
• Machine: /etc/opencode/opencode.jsonc plus managed preferences — highest precedence, for teams.
• Terminal: ~/.config/opencode/cli.json — global only, no per-project CLI config. Change from TUI with Ctrl+P then Open settings, or merge inline with OPENCODE_CLI_CONFIG_CONTENT.

Give every project persistent guidance with AGENTS.md and commit it. Run /init once to generate it, then keep build, test and style rules there. Global defaults go to ~/.config/opencode/AGENTS.md, repo-wide rules to the root file, package-specific rules to nested files. V2 reads only AGENTS.md, there is no CLAUDE.md fallback.

Safe permission baseline in the project opencode.jsonc — ask for shell, allow inspection, never push:

vi opencode.jsonc

{ "$schema": "https://opencode.ai/config.json", "model": "opencode/deepseek-v4.1-flash-free", "permissions": [ { "action": "shell", "resource": "*", "effect": "ask" }, { "action": "shell", "resource": "git status *", "effect": "allow" }, { "action": "shell", "resource": "git diff *", "effect": "allow" }, { "action": "shell", "resource": "npm test *", "effect": "allow" }, { "action": "shell", "resource": "git push *", "effect": "deny" }, { "action": "read", "resource": "*.env", "effect": "deny" } ] }

Hard team blocks that projects cannot override go to policies, not permissions. Example: deny a provider or a dangerous tool globally. Context control: formatter: true formats after write and edit, tool_output caps lines and bytes, compaction keeps recent tokens on long sessions, warming keeps idle sessions warm at a small token cost. Reload without restart after edits:

opencode reload

Skills and agents: where to put them

Skills hold checklists, agents hold identity. Both are files in the repo, both work the same on the free OpenCode model, GPT 6 Luna and Claude Opus 5.5 — only the strictness you trust them with differs. Full guides with five complete skills and four complete agents: Writing skills for AI assistants and Creating agents in OpenCode.

Where each file lives, as tree output. Every element links to the chapter where it is explained:

my-app/ ├── opencode.jsonc ├── AGENTS.md ├── .opencode/skills/ │ ├── commit-style.md │ ├── db-migrate/ │ │ ├── SKILL.md │ │ ├── scripts/rollback.sh │ │ └── references/policy.md │ ├── test-writer/ │ │ └── SKILL.md │ └── api-review/ │ └── SKILL.md ├── .opencode/agents/ │ ├── triage.md │ ├── builder.md │ ├── reviewer.md │ └── team/orchestrator.md └── .opencode/commands/ ├── review.md └── build-feature.md

Model split that works in practice: triage on the free model explains and routes without editing, builder on Luna implements with test-writer, reviewer on Opus 5.5 judges with api-review. One opencode.jsonc at the project root ties it together:

vi opencode.jsonc

{ "$schema": "https://opencode.ai/config.json", "model": "opencode/deepseek-v4.1-flash-free", "skills": ["./team-skills"], "permissions": [ { "action": "shell", "resource": "*", "effect": "ask" }, { "action": "shell", "resource": "npm test *", "effect": "allow" }, { "action": "shell", "resource": "git push *", "effect": "deny" } ], "agents": { "builder": { "model": "opencode/gpt-6-luna" }, "reviewer": { "model": "opencode/claude-opus-5-5" } } }

Daily calls that use this layout: With triage, explain src/auth.ts login flow, then With builder and @test-writer, add validation and keep tests green, then Use the reviewer subagent with @api-review on the staged diff. Personal experiments go to ~/.config/opencode/skills/ and ~/.config/opencode/agents/, team contracts stay in the repo and get committed.

Three models, one project

Use all three models on the same checkout, each with a fixed role. The trick is not three checkouts — it is one layout plus a routing table so each agent knows where to look and what to ignore:

1. One AGENTS.md routes all three. Keep the root file tiny and let it point at roles, not at model names. Every agent reads it on start, so it is the single map of where to look:

# Project instructions - Triage: explain only, never edit, never read .env files. - Build: implement in src/, tests in tests/, run npm test -- --run <file>. - Review: read staged diff only, rubric in .opencode/skills/api-review/SKILL.md. - DB rules: .opencode/skills/db-migrate/references/policy.md is normative.

Nested area files refine, never repeat. Example src/database/AGENTS.md with two lines about migration naming is read when that dir is explored — triage sees it on explain, builder sees it on edit, reviewer sees it on audit.

2. Descriptions are the signposts. The model picks skills and subagents from description text alone, so write each description as a route: verb plus path plus negative. Compare:

description: Safe database migration with review and rollback plan description: Review API diffs for bugs, security, and missing tests

Agent descriptions do the same for the parent: Explains code and sorts tasks without editing versus Final correctness and security pass over staged diffs. The orchestrator then needs no model names, only intent: With team/orchestrator, plan cursor pagination for orders fans out to explore, builder and reviewer by description match.

3. Gate skills per agent so each role sees a different shelf. Same skill store, different visibility. Triage sees nothing to load, builder sees the two working checklists, reviewer sees only the strict rubric, all in opencode.jsonc:

{ "$schema": "https://opencode.ai/config.json", "model": "opencode/deepseek-v4.1-flash-free", "permissions": [ { "action": "skill", "resource": "*", "effect": "allow" }, { "action": "shell", "resource": "git push *", "effect": "deny" }, { "action": "read", "resource": "*.env", "effect": "deny" } ], "agents": { "triage": { "model": "opencode/deepseek-v4.1-flash-free", "permissions": [ { "action": "edit", "resource": "*", "effect": "deny" }, { "action": "skill", "resource": "*", "effect": "deny" } ] }, "builder": { "model": "opencode/gpt-6-luna", "permissions": [ { "action": "skill", "resource": "*", "effect": "deny" }, { "action": "skill", "resource": "test-writer", "effect": "allow" }, { "action": "skill", "resource": "db-migrate", "effect": "allow" } ] }, "reviewer": { "model": "opencode/claude-opus-5-5", "permissions": [ { "action": "edit", "resource": "*", "effect": "deny" }, { "action": "shell", "resource": "*", "effect": "deny" }, { "action": "skill", "resource": "*", "effect": "deny" }, { "action": "skill", "resource": "api-review", "effect": "allow" } ] } } }

4. Handoff in one session, cheapest first. Stay in one session so context accumulates, escalate the model only when the role changes:

With triage, explain src/auth.ts login flow and route the refresh bug as small fix or feature

With builder and @test-writer, implement the small fix with three tests, show git diff --stat and stop

Use the reviewer subagent with @api-review on git diff --cached, verdict ship or fix first

What passes between steps: triage returns a two-line route plus file list, builder returns a diff plus test output, reviewer returns findings with file and line plus a verdict. Nothing else moves — no copy of the whole repo, no re-read of policy files, because all three resolve the same relative paths from the same SKILL.md base dirs. Keep secrets out of step one: a free model can be a contributor tier that trains on prompts, so route .env and customer code straight to Luna or Opus or a local model.

Aredel trio on one checkout

Same trio pattern applied to the aredel repo itself: a PHP site with over 7000 PHP files in its docroot. Repo root and docroot:

/home/andrei/github/aredel

container/src/

The layout below is the result of the 2026-10-22 audit: skills in one place that OpenCode and Claude Code both read, the same three roles in each tool, and a launcher that checks the pinned model ids. Skill bodies are in Aredel project map:

aredel/ ├── AGENTS.md ├── opencode.jsonc ├── .claude/skills/ │ ├── aredel-map/ │ ├── aredel-page/ │ ├── aredel-blocks/ │ ├── aredel-css/ │ ├── aredel-tooling/ │ ├── aredel-verify/ │ └── ai-style/ ├── .claude/agents/ ├── .opencode/agents/ │ ├── triage.md │ ├── builder.md │ └── reviewer.md ├── .opencode/commands/review.md └── container/tools/ai/opencode.sh

Placement rules:

• One shared shelf: all skills in .claude/skills/<name>/SKILL.md at the repo root. OpenCode reads that directory as a compatibility location, Claude Code natively, so both tools load the same procedures.
• No skill inside the docroot: ai-style lives with the others and limits itself to container/src/ai/ through its description. A copy under container/src/ai/.opencode/ would be uploaded with the site.
• Heavy text in references: long checklists live in references/ beside SKILL.md, bodies stay under 60 lines. Every skill is advertised; a hidden skill is one the role that needs it never finds.

Role to skill wiring for aredel, cheapest first:

Root AGENTS.md is a routing table from task to skills plus the few rules every task needs; the skills carry the procedures. Its full text and the reasons behind each change are in Agent setup audit.

Old and new features

Classic daily set (still here). Full-screen TUI plus mini for small terminals, desktop app with attached browser control, and web UI via opencode pair and opencode serve. Type @ to fuzzy-search a file and attach its content, like @src/auth.ts (Add file context with @), ! for one-shot shell, / for slash commands, Tab or Shift+Tab to cycle Build and Plan agents. /new, /sessions, /undo and /redo with Git-backed filesystem snapshots, /share, /editor with EDITOR, /btw for side questions that do not pollute context. CLI workhorses: run for one-shot answers and CI, session list/export/import, stats --cost --models, api GET /api/session, debug config/paths.

Agents: 4 built-ins that matter. build (primary, default coder), plan (primary, explores without editing project files), general (subagent for research and multi-step work), explore (subagent, read-only search of code and web). Override or add your own in .opencode/agents/reviewer.md or under agents in config, with own model, system prompt, steps limit, color, and permissions. Subagents run with fresh context in foreground or background — the parent stays usable.

Tools: small fixed core plus extensions. Files: read, glob, grep, edit, write (patch for multi-file changes on GPT models). Commands: shell with foreground timeout and background mode for dev servers. Web: webfetch, websearch with selectable provider. Interaction: question pauses and asks you to choose, skill loads one skill body on demand, subagent launches a child agent, execute runs parallel tool calls in Code Mode without flooding context. MCP servers add tools named server_tool, browser namespace drives the desktop browser (tabs, snapshots, clicks, screenshots, Lighthouse). Every tool checks ordered permissions: last match wins, allow / ask / deny, with durable per-project Allow always approvals.

New in V2 worth learning. Model variants #high, #low, #fast per model, custom variants and aliases in config, per-provider and per-model settings, headers and body overlays, automatic prompt-cache breakpoints (Anthropic format, Alibaba format). Local discovery for Ollama, LM Studio and vLLM with background refresh. Compaction: automatic local summaries plus native provider compaction checkpoints with keep.tokens and buffer budgets. Warming with idle interval. Named references to local dirs or git repos as supporting context. Git worktree creation and session move for parallel features. New plugin shape (hooks, transforms, tools, TUI and RPC extensions) — V1 plugins do not run, port them. ACP server over stdin and stdout for editor integrations, SDK and generated TypeScript client for the HTTP API, OpenAPI at /openapi.json.

Skills, commands, MCP, policies. Skills are reusable instruction packs: .opencode/skills/git-release/SKILL.md with scripts and references beside it, auto-discovered from global, project, and explicit skills dirs or HTTP catalogs, advertised by description and loaded with @skill-id. Commands are prompt templates: .opencode/commands/review.md with $ARGUMENTS, $1, $2 and shell blocks !`git diff --cached`, optional agent, model and background subagent: true. MCP connects local and remote tools: opencode mcp add playwright --global -- bunx @playwright/mcp, OAuth via /mcps, secrets via {env:KEY} never in plain text. Policies hard-deny providers, tools, MCP, skills and plugins after permissions run.

Effective workflows

1. Free-first daily loop (free OpenCode model). Set the free model as default, do everything with it, escalate only on failure. F2 cycles recent models, Ctrl+X then M opens the picker without losing context.

opencode

Explain lines 1-120 of @src/auth.ts, then list edge cases you are unsure about

Add validation to login, keep the public API, run npm test and show the diff

If the answer is weak, stay in the same session and say Retry the fix with opencode/claude-opus-5-5, keep the passing tests green. Reserve Opus for the final pass, not for every keystroke — this alone cuts cost by an order of magnitude.

2. Plan then Build (hard features). Never let a strong model edit on the first prompt. Hit Tab for Plan mode, describe the feature like to a junior developer, iterate, then Tab back to Build.

Plan: add cursor pagination to /api/orders. Show files to touch, schema change, and test plan. No edits yet.

Looks good, now implement step 1 and 2 only, then stop for review

Plan agent cannot edit project files by default, so it cannot break code while thinking. Save the plan to a file when it spans days.

3. Parallel explore before you touch code. Let subagents map unknown code while you keep typing. One call, fresh context each:

Ask the explore subagent to map the auth flow and return key files, then ask general to compare with docs in references/docs

Same idea in Code Mode: read package.json and README in parallel with execute, then return only setup details. Background subagents notify when done — start two, keep working in the parent.

4. Team review command on Opus 5.5. Create once, reuse forever. File .opencode/commands/review.md:

--- description: Review staged changes agent: general model: opencode/claude-opus-5-5 --- Review this diff for bugs, security and missing tests: !`git diff --cached`

Run /review, report findings in severity order with file and line

Pair with a read-only reviewer agent that denies edit and shell so review never mutates code. Run it in background with subagent: true while you write the next feature.

5. Skills plus AGENTS.md for team conventions. Put repeatable team knowledge into a skill, not into every prompt. Example .opencode/skills/db-migrate/SKILL.md with migration policy and rollback script beside it. Mention @db-migrate once and the agent loads the full checklist. Keep AGENTS.md tiny: build, typecheck and test commands, where queries live, what never to edit. Commit both so every session and every teammate gets the same guidance.

6. CI review, worktrees, and long sessions. One-shot review in GitHub Actions with a cheap model, no TUI:

opencode run --standalone --model opencode/gpt-6-luna "Review this repository for correctness and summarize issues"

Parallel features without branch pain: create a worktree, move the session into it, keep main clean. For sessions over an hour enable automatic compaction with a generous keep.tokens budget, and commit or session export before big undos — snapshots are convenience, not backup, and shell side effects are never rolled back.

Troubleshooting

• Command not found after install: restart the terminal (PATH update), rerun the V2 installer, check npm global bin dir on PATH. Confirm with opencode --version, fix with opencode upgrade.
• No models listed: you skipped connect — run /connect or opencode auth login opencode. For Ollama confirm ollama serve and ollama list. Remember catalog, credentials and config are location-scoped: a model available in one project may be missing in another.
• Free model gone or rate-limited: free ids rotate — take the next live id from the fallback order, switch default to opencode/gpt-6-luna, or fall back to local Ollama. Fetch https://opencode.ai/inference/v1/models for the live list.
• Unexpected charges: set monthly workspace and per-member limits in Console, enable auto-reload deliberately, review opencode stats --cost --models. Session-title generation uses cheap models and shows up in history. Use the free model for drafts, Luna for routine paid work, Opus 5.5 only for the hard pass.
• Weak answers: add file context with @, switch agent with Shift+Tab, escalate model with F2. Keep AGENTS.md short and exact — long vague instructions hurt more than they help.
• Service stuck or odd behavior: opencode service restart then opencode service status, compare with opencode --standalone, inspect ~/.local/share/opencode/log/opencode.log with OPENCODE_LOG_LEVEL=DEBUG for one repro. Do not delete the database or service registration while diagnosing.
• MCP needs sign-in: opencode mcp list shows status — open /mcps, select the server and sign in. Do not paste OAuth secrets into config, use {env:KEY}.
• V1 config confusion: bash is now shell, task is now subagent, permission is now ordered permissions, snapshot is snapshots, terminal settings moved to cli.json. Ask OpenCode to migrate the config and preserve behavior, then verify models, agents, permissions and MCP before deleting the V1 backup.

Official sources:

• opencode.ai/v2/docs
• opencode.ai/v2/llms.txt
• opencode.ai/docs/console/models (ids, endpoints, pricing, privacy)
• github.com/anomalyco/opencode
• openrouter.ai

Article author: Arthur Isaev