opencode is an open-source AI coding agent for the terminal. It runs as a TUI (also available as a desktop app and IDE extension), understands project context, and can read/write files and run shell commands. It is provider-agnostic — works with 75+ LLM providers via the AI SDK and Models.dev, including local models — and is heavily configurable through JSON config, custom agents, commands, and plugins.

On Windows, WSL is recommended. opencode auto-updates on startup by default ("autoupdate": false or "notify" to change).

opencode ships two primary agents you toggle with Tab:

The typical flow: draft an approach in Plan, iterate on it, then switch to Build to implement. Use /undo and /redo (repeatable) to roll changes back and forth.

Agents are specialized assistants with their own prompt, model, and tool permissions. Two kinds:

Hidden system agents (compaction, title, summary) run automatically.

Define agents in opencode.json or as markdown files in ~/.config/opencode/agents/ (global) or .opencode/agents/ (project). The filename becomes the agent name.

Key options: description (required), mode (primary/subagent/all), model, prompt ({file:./prompt.txt}), temperature/top_p, steps (max agentic iterations), permission, color, hidden, disable. Run opencode agent create for an interactive scaffold. Control which subagents an agent may spawn with permission.task.

Config is JSON/JSONC validated against https://opencode.ai/config.json. Files are merged (not replaced), later sources overriding earlier ones:

TUI-specific settings live in a separate tui.json (theme, keybinds, scroll, notifications). Inspect the fully resolved config with opencode debug config.

compaction (auto context compaction), snapshot (file-change tracking for undo; disable on huge repos), watcher.ignore (glob ignore patterns), share (manual/auto/disabled), shell, attachment.image (resize limits), disabled_providers/enabled_providers.

Model IDs are provider/model-id (e.g. anthropic/claude-sonnet-4-5, opencode/gpt-5.1-codex). Pick one in the TUI with /models, set a default via the model key, or override per-invocation with --model. Models that are strong at both code generation and tool-calling work best (Claude Opus/Sonnet 4.5, GPT 5.x, Gemini 3 Pro, etc.).

Per-model options and variants are configured under provider.<id>.models:

Variants (e.g. Anthropic high/max thinking budgets, OpenAI reasoning-effort levels) are cycled in the TUI with variant_cycle. Local models run via providers like LM Studio or Ollama.

Tools are the actions the LLM can take. Built-ins: bash, edit, write, read, grep, glob, apply_patch, lsp (experimental), skill, todowrite, webfetch, websearch, question. Internally grep/glob use ripgrep, so .gitignore is respected (add a .ignore file to override).

Extend with custom tools (functions defined in config) or MCP servers (Model Context Protocol — external tools, DB access, API integrations) via the mcp key. Plugins add tools, hooks, and integrations from .opencode/plugins/ or npm (plugin key).

Permissions decide whether a tool runs automatically (allow), prompts (ask), or is blocked (deny). Defaults are permissive — most allow, but doom_loop and external_directory default to ask, and .env reads are denied.

Object syntax matches against tool input (bash commands, file paths, URLs…) with glob wildcards (*, ?); the last matching rule wins, so put "*" first and specific rules after. Permission keys: read, edit (covers write/apply_patch), glob, grep, bash, task, skill, lsp, question, webfetch, websearch, plus the guards external_directory (paths outside the workspace) and doom_loop (same call repeated 3×). Agents can override globally-set permissions, and the same pattern syntax gates MCP tools ("mymcp_*": "deny"). The legacy boolean tools config is deprecated in favor of permission.

Separate from permissions: experimental.policies controls which resources (currently LLM providers) opencode may use — useful for org-level provider allow/deny lists. Statements have effect (allow/deny), action (provider.use), and a wildcard resource; last match wins, global config beats project config.

Project-specific instructions live in AGENTS.md (like Cursor rules). /init generates it from your repo — build/test commands, structure, conventions, gotchas — and improves an existing one in place. Lookup precedence: local AGENTS.md (walking up) → global ~/.config/opencode/AGENTS.md → ~/.claude/CLAUDE.md (Claude Code compatibility fallback). Pull in extra files via the instructions array (supports globs and remote URLs).

Reusable prompts triggered with /name, alongside built-ins like /init, /undo, /redo, /share, /help. Define in config or as markdown in ~/.config/opencode/commands/ (global) or .opencode/commands/ (project).

Placeholders: $ARGUMENTS (all args), $1/$2/… (positional), !`cmd` (inject shell output), @file (inline file contents). subtask: true forces the command to run as a subagent so it doesn't pollute primary context.

opencode runs language-specific formatters after writing/editing files. Disabled by default — enable with "formatter": true, or use an object to configure overrides and custom formatters. Built-ins include prettier, biome, gofmt, rustfmt, ruff, shfmt, nixfmt, clang-format, and many more (each requires its tool/config present).

$FILE is replaced with the file path. (LSP servers are similarly configured under the lsp key.)

Set the theme in tui.json ("theme": "tokyonight") or pick one with /theme. Built-ins include tokyonight, catppuccin, gruvbox, nord, everforest, one-dark, matrix, and system (adapts to your terminal). Truecolor (24-bit) is recommended. Custom themes go in ~/.config/opencode/themes/*.json.

Keybinds are customized in tui.json under keybinds (merged with defaults — only override what you change). They use a leader key (default ctrl+x). Notable defaults:

/share creates a link to the current conversation (off by default; the share config key sets manual/auto/disabled).

opencode is one of several terminal AI tools tracked here — see also crush and mods. It is developed under the Anomaly/SST umbrella.