Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Loaded automatically when the description matches the active task. Read only the section needed.
Use this skill when
Installing or updating the opencode CLI (curl ... | bash, brew install, npm i -g opencode-ai)
Authoring opencode.json / opencode.jsonc (project) or ~/.config/opencode/opencode.json (user)
Writing or editing AGENTS.md for project memory (same file used by OpenAI Codex)
Configuring providers in opencode.json: provider.* for BYOK (Claude, OpenAI, Gemini, Mistral, Groq, Ollama, etc.)
Defining agents in opencode.json: agent.* (build/plan/custom) or .opencode/agents/<name>.md
Setting up MCP servers in opencode.json: mcp.* (stdio + http)
Running headless: opencode run "...", JSON output, CI integration
Using ACP (Agent Client Protocol) to drive OpenCode from Zed editor / IDE
Switching themes via tui.json: theme (tokyonight, dracula, etc.)
Migrating between OpenCode, Claude Code, and OpenAI Codex configs
Picking the right CLI: when multi-provider/BYOK is the requirement
Do not use this skill when
Task is Claude Code CLI specifics (settings.json hooks, .claude/skills, /loop) — use claude-code
Task is OpenAI Codex CLI (Rust, config.toml, codex exec) — use codex
Task is hosting the OpenCode server on Cloudflare / SST — focus here is the CLI client
Task is general LLM agent design (planning, evaluation, benchmarking) — use agent-evaluation
Task is authoring a Claude Code SKILL.md file — use skill-evaluation
User wants the deprecated 2021-era OpenAI Codex completion model — that's been discontinued; modern Codex is codex skill
Purpose
OpenCode (currently maintained by Anomaly at github.com/anomalyco/opencode, originally github.com/sst/opencode) is the leading open-source, multi-provider terminal coding agent. Unlike Claude Code (Anthropic-only) and OpenAI Codex (OpenAI-only), OpenCode is BYOK across 75+ providers including Anthropic, OpenAI, Google, Mistral, Groq, Together, and local models via Ollama. Built with Bun + TypeScript (with a Go TUI), 100K+ stars, Apache-2.0.
This skill covers the CLI operating surface: install, auth across providers, opencode.json config schema, agents (built-in build/plan + custom markdown agents), MCP servers, ACP protocol (for editor integration), headless opencode run, and the migration path to/from Claude Code and OpenAI Codex.
What this skill does NOT cover: hosting an OpenCode server on Cloudflare/SST (infra, not CLI), general agent benchmarking (agent-evaluation), or building custom MCP servers (mcp-builder).
Capabilities
Installation & auth
Native install script: curl -fsSL https://opencode.ai/install | bash. Brew: brew install sst/tap/opencode. npm SDK: npm i -g opencode-ai. Verify: opencode --version. Auth: opencode auth login opens a provider picker and stores credentials in ~/.local/share/opencode/auth.json. Per-provider env vars (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, OLLAMA_BASE_URL) also work directly.
Configure once in provider, pick per-agent in agent.<name>.model. Provider format: <provider>/<model-id>. Examples: anthropic/claude-sonnet-4-6, openai/gpt-5.5, google/gemini-2.5-pro, groq/llama-3.3-70b-versatile, ollama/codellama:34b. Failover is provider-specific (e.g., OpenRouter allow_fallbacks/order, Vercel gateway order) — there is no generic top-level provider.fallback key. Use opencode models to list everything available with current auth.
Two built-in primary agents: build (full tools, default) and plan (read-only, drafts a plan). Switch live with Tab in TUI or --agent flag. Custom agents: define in opencode.json: agent.<name> OR as markdown at ~/.config/opencode/agents/<name>.md / .opencode/agents/<name>.md. Frontmatter: description, model, tools, prompt. Subagents (non-primary) are called by primary agents via task delegation.
Configure in opencode.json: mcp. Same protocol as Claude Code/Codex — server binaries are interchangeable. Transports: local (stdio) and remote (http/sse). Example:
OpenCode permission model is simpler than Claude Code's: per-agent tools allowlist (disable write, edit, bash, web per agent), plus a runtime approval prompt by default. --auto flag or permissions.auto config skips prompts. There are no native hooks — wrap opencode run in a shell script for post-edit formatting.
ACP (opencode serve --acp) exposes OpenCode as an Agent Client Protocol server for editors (Zed native, VS Code via SDK). Headless: opencode run "<prompt>" --json returns a JSONL event stream. AGENTS.md is shared with Codex; CLAUDE.md is Claude Code's analogue. See references/agents.md, references/interop.md, references/migration.md.
Behavioral Traits
Reads opencode.json and AGENTS.md first when entering a project
Picks the provider per task: Anthropic for hard reasoning, Groq/Ollama for bulk/fast, Gemini for long context
Uses build agent by default; switches to plan for unfamiliar code or large refactors
Defines a code-reviewer custom agent with write: false, edit: false for read-only review work
Uses OpenRouter / Vercel gateway order + allow_fallbacks for per-model failover (no generic top-level provider.fallback exists)
Wraps opencode run in a shell script when hooks-like behaviour is needed (OpenCode has no native hooks)
Uses ACP mode when working inside Zed/VS Code rather than a separate TUI
Stores secrets in {env:VAR} interpolation, never inline in opencode.json
Commits opencode.json and AGENTS.md; gitignores .opencode/local.json if present
Important Constraints
NEVER commit API keys inline in opencode.json — use {env:VAR} or {file:~/.secrets/...}
NEVER assume Claude Code hooks have an OpenCode equivalent — they don't; use shell wrappers
NEVER use --auto outside a sandboxed environment (devcontainer/VM/CI runner)
NEVER mix Anomaly fork and SST origin docs — they diverged in late 2025; check which repo your install came from
NEVER omit the provider prefix in model IDs — claude-sonnet-4-6 is ambiguous; use anthropic/claude-sonnet-4-6
ALWAYS run opencode models after opencode auth login to verify the provider is reachable
ALWAYS pin OpenCode version in CI: install script accepts VERSION=1.0.92 bash
ALWAYS write subagent system prompts in their markdown body (not in opencode.json) when they exceed ~5 lines
Related Skills
90%-filter applied. ✓ = active; rest are cascade markers.
Cousin CLI agents
✓ claude-code — Anthropic's official CLI (depth in skills/hooks/subagents)
✓ codex — OpenAI's official CLI (Rust, OpenAI-only)
