OpenCode Primer

Everything you need to know about OpenCode — from your first prompt to custom agents, skills, plugins, and MCP integrations. Clear mental models, real examples, every fact verified against the current release.

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

Who this is for: Developers using (or about to use) OpenCode. Beginners get a guided path; power users get depth on Custom Commands, Skills, Plugins, MCP, and Agents.

⚖️ Not affiliated with the OpenCode team. This is a community-maintained guide. For canonical sources, check opencode.ai/docs and github.com/anomalyco/opencode.

💡 Pro Tip: If this guide saves you an afternoon, a ⭐ helps other developers find it.

🧭 Choose your path

Getting started

What is OpenCode?

OpenCode is an open-source AI coding agent — a terminal app (TUI), desktop app, and IDE extension that reads your repo, runs commands, edits files, and talks to any LLM you point it at. Maintained by Anomaly, MIT-licensed — and as of July 2026 the most-starred coding agent on GitHub (182K+ stars), with 8M monthly users by the founder's count.

Three things it does that a chat UI can't:

• Reads your actual repo — not pasted snippets. Greps your files, follows imports, grounds answers in real context using built-in read/grep/glob tools.
• Edits in place and runs your stack — diff-aware edit/write/apply_patch, then bash to run your tests, linter, or build on the spot.
• Composes with the rest of your toolchain — multi-provider models, custom slash commands, agent skills, JS/TS plugins, MCP servers, LSP, formatters, and an HTTP server for CI use.

Three interfaces:

opencode                                       # start TUI in the current repo
opencode run "fix the failing test in src/api.test.ts"
opencode serve --port 4096                     # headless server

OpenCode sits in the same space as Claude Code, Codex CLI, and Cursor — same problem, different trade-offs. None is universally better; pick the one whose model, surface, and ecosystem fit your workflow. (The field consolidated hard in 2026: Gemini CLI was retired in June in favor of the closed-source Antigravity CLI, and Roo Code shut down in May.)

⚠️ AI-coding caveat: OpenCode (like every coding agent) can produce wrong code, miss edge cases, hallucinate APIs, and over-apply patterns. You're still the reviewer. Read diffs before accepting, run tests, and don't auto-approve destructive operations on code you care about.

When OpenCode isn't the right tool

When something else fits better:

• Want a polished single-vendor product → Claude Code or Codex CLI.
• Deeply embedded in VS Code workflow → Cursor or GitHub Copilot.
• Want a small Python tool you can read end-to-end → Aider (note: development has slowed markedly in 2026).
• Don't want to manage provider keys → a managed hosted product, or OpenCode Go.

OpenCode's trade-off: flexibility and openness over polish and single-vendor integration. Worth it for many use cases; not all.

Setup

⏱️ 5 minutes from zero to first AI-assisted commit.

1. Install

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

Other supported installers (pick whichever you already use):

npm i -g opencode-ai@latest         # npm / pnpm / yarn / bun all work
brew install anomalyco/tap/opencode # macOS / Linux
scoop install opencode              # Windows
choco install opencode              # Windows
sudo pacman -S opencode             # Arch
paru -S opencode-bin                # Arch (AUR)
mise use -g github:anomalyco/opencode      # mise users
docker run -it --rm ghcr.io/anomalyco/opencode  # Docker

A desktop app for macOS / Windows / Linux is in beta at opencode.ai/download.

2. Authenticate

opencode auth login                  # interactive provider picker
opencode auth list                   # see who you're signed in to

Or from inside the TUI: /connect. Provider options covered in the next section.

3. First prompt

cd ~/your-project
opencode

Try one of these:

• explain what this codebase does
• add a README section about installation
• find and fix the failing test in src/api.test.ts

4. Generate an AGENTS.md

/init

/init generates an AGENTS.md — your project's "house rules" that OpenCode reads every session. Commit it. More in Prompt Engineering.

📝 Coming from Claude Code? OpenCode reads CLAUDE.md as a fallback if no AGENTS.md exists. Disable with OPENCODE_DISABLE_CLAUDE_CODE=1 once migrated.

5. (Bonus) See a real configured project

This repo's own .opencode/ directory is a working example:

Models & Providers

OpenCode is provider-agnostic. Four ways to plug in a model — pick whichever fits your accounts, budget, and privacy posture: