OpenCode
This is a practical developer guide to OpenCode from anomalyco/opencode. It is for developers who want to understand what OpenCode is good at, how to set it up, and how to use its agent, tool, skill, and configuration model in a real project.
This guide is based on the official OpenCode documentation and the official GitHub repository, reviewed on June 24, 2026.
1. What OpenCode is​
OpenCode is an open-source AI coding agent that can run as:
- a terminal UI
- a desktop app
- a web-connected interface
- an IDE extension
The official docs position it as a coding agent rather than just a chat wrapper. Its design centers on:
- terminal-first development
- model and provider flexibility
- agent-based workflows
- deep customization through config, commands, skills, and plugins
In practice, OpenCode sits in the same family as tools like Claude Code, Codex CLI, and Aider, but with a stronger emphasis on being open, provider-agnostic, and adaptable to different local or team setups.
2. Why developers use it​
From the official docs, OpenCode is strongest when you want one agent shell that can be shaped to your workflow instead of forcing you into one provider or one UI.
| Capability | Why it matters |
|---|---|
| Open-source agent shell | Easier to inspect, extend, and adopt in internal workflows. |
| Terminal + desktop + web + IDE surfaces | You are not locked to one interface. |
| 75+ providers plus local models | Good fit for cost, privacy, and experimentation trade-offs. |
| Plan and Build agents | Clean separation between planning and making changes. |
| Custom agents and subagents | Useful for code review, docs, debugging, or internal team workflows. |
| Skills, commands, plugins, MCP | Lets you turn repeatable behavior into reusable building blocks. |
| Headless and scriptable CLI | Works for automation, CI, and backend-attached workflows. |
| Shareable sessions | Useful for code review, debugging, and pair-programming handoff. |
That makes OpenCode especially attractive for:
- teams that want one tooling layer over many model providers
- developers who prefer a terminal-native workflow
- organizations that care about local control and extensibility
- users who want something more configurable than a closed vendor CLI
3. Installation and first run​
The official intro page recommends the install script as the easiest path:
curl -fsSL https://opencode.ai/install | bash
It can also be installed with package managers:
npm install -g opencode-ai
brew install anomalyco/tap/opencode
The docs also list bun, pnpm, yarn, Chocolatey, Scoop, mise, Docker, release binaries, and Arch packages.
First session​
cd /path/to/project
opencode
After connecting a provider, the official docs recommend running:
/init
This makes OpenCode analyze the project and generate an AGENTS.md file in the project root.
Why AGENTS.md matters​
The docs explicitly recommend committing AGENTS.md to git. That is important because it turns local agent behavior into shared project context:
- project structure
- coding patterns
- expected conventions
- workflow guidance for future sessions
That is one of OpenCode's best habits and a good team practice.
4. Core workflow in daily development​
OpenCode's docs present a workflow that is more structured than "just ask the model to code."
Use Plan mode before Build mode​
OpenCode ships with two built-in primary agents:
- Build for implementation work
- Plan for analysis without changing files
You switch between them with the Tab key.
This is a meaningful design choice: planning is not just a prompt style, it is a separate agent mode with more restrictive permissions.
Ask questions against files directly​
The docs recommend attaching file context inline:
"@packages/functions/src/api/index.ts"
How is authentication handled in @packages/functions/src/api/index.ts
This makes OpenCode useful not only for writing code, but also for codebase onboarding and architecture discovery.
Use Plan mode for bigger work​
The official workflow for feature work is:
- switch to Plan
- describe the feature in detail
- iterate on the plan
- switch back to Build
- ask OpenCode to implement it
That is a strong best practice, especially for:
- multi-file changes
- unfamiliar codebases
- changes with UI, data, and API impact
- refactors where you want to sanity-check the approach first
Image-aware planning​
The intro docs explicitly support dragging images into the terminal so OpenCode can use them as visual reference. That is unusually practical for:
- UI tasks
- design matching
- reverse engineering screenshots
Undo, redo, and sharing​
OpenCode includes built-in commands for session control:
/undo/redo/share
That gives you a lightweight recovery and collaboration loop without leaving the agent workflow.
5. Configuration model​
One of OpenCode's biggest differentiators is how much of its behavior is intentionally configurable.
JSON and JSONC config​
The official config docs support both:
opencode.jsonopencode.jsonc
This is small, but it matters. JSONC makes long-lived team config much easier to maintain.
Config layers are merged​
The docs say configuration is merged, not replaced, across several layers, including:
- remote organizational defaults
- global user config
- custom config path
- project config
.opencodedirectories- inline environment overrides
- managed config files
- macOS managed preferences
That makes OpenCode more enterprise-friendly than many terminal coding tools because it can support:
- personal defaults
- repository-local behavior
- organization-wide policy
- admin-enforced restrictions
Project-local structure​
The docs treat .opencode/ as a first-class extension area for things like:
agents/commands/plugins/skills/tools/themes/
That is a strong design because it makes agent behavior part of the repository instead of hiding it in one developer's home directory.
6. Agents, subagents, and skills​
OpenCode is not just "one bot with one prompt." It has a real agent model.
Built-in primary agents​
- Build: default implementation agent with broad tool access
- Plan: analysis-first agent with restricted change permissions
Built-in subagents​
The official agents docs describe built-in subagents including:
- General for broader multi-step work
- Explore for fast read-only codebase exploration
- Scout for external docs and dependency research
This is useful because it gives OpenCode a built-in division of labor instead of forcing one giant agent to do everything.
Custom agents​
You can define agents in config or Markdown files and tune:
- prompt
- model
- mode
- permissions
- temperature
- step limits
This makes it easy to create targeted agents such as:
- code reviewer
- docs writer
- security auditor
- debug investigator
Skills​
OpenCode supports SKILL.md-based reusable instructions and loads them on demand through its skill tool.
A particularly important detail from the official docs: OpenCode can discover skills from:
.opencode/skills/.claude/skills/.agents/skills/- matching global directories in the user's home folder
That means OpenCode can fit very well into teams that already invested in Claude-style or agent-compatible skill libraries. In practice, this lowers migration friction and lets you reuse procedural knowledge across tools.
7. Commands, tools, plugins, and MCP​
This is where OpenCode becomes more than a terminal chatbot.
Custom commands​
OpenCode lets you create slash commands either in config or Markdown files, for example:
/test/component Button/review-changes
The command system supports:
- prompt templates
- arguments such as
$ARGUMENTS,$1,$2 - inline file references with
@file - shell output injection
- per-command model and agent overrides
That is extremely useful for repeatable workflows. In many teams, this is the fastest route from "we often do this manually" to "we turned it into a reusable AI command."
Tools and permissions​
The official tools docs list built-in tools such as:
bashreadeditwritegrepglobapply_patchskilltodowritewebfetchwebsearch
OpenCode's permission model can allow, deny, or require approval per tool or per pattern.
That is powerful, but there is an important caveat:
The official config docs say that, by default, OpenCode allows all operations without requiring explicit approval. For real project work, you should usually tighten this with permission rules, especially for edit, bash, task, and external access.
MCP servers​
OpenCode includes explicit MCP management commands such as:
opencode mcp addopencode mcp listopencode mcp auth
This makes it a good fit for teams building internal tool ecosystems around MCP instead of relying only on built-in file and shell access.
Plugins​
OpenCode also supports plugins and can install them through:
opencode plugin <module>
That means you can keep your core setup lean and add integrations only where they create value.
8. Providers and model flexibility​
The official provider docs say OpenCode uses AI SDK plus Models.dev and supports 75+ LLM providers, in addition to local models.
What that means in practice​
OpenCode is a strong choice when you want to:
- move between Anthropic, OpenAI, OpenRouter, xAI, Bedrock, Azure, and others
- route through a gateway or proxy
- run local models behind an OpenAI-compatible endpoint
- standardize one agent workflow while changing only the backend model
Helpful commands​
The official CLI supports:
opencode auth login
opencode auth list
opencode models
And for quick non-interactive work:
opencode run "Explain how this module works"
Local and remote operating modes​
The CLI docs also show that OpenCode can run as:
- an interactive TUI
- a non-interactive CLI runner
- a headless HTTP server with
opencode serve - a web-backed interface with
opencode web - a remote-attached TUI with
opencode attach
That makes it more flexible than tools that only support one local interactive mode.
9. Best practices​
If you adopt OpenCode seriously, these are the best practices most strongly supported by the official docs.
1. Commit AGENTS.md​
Treat AGENTS.md as shared project memory, not as disposable local output.
2. Use Plan first for non-trivial tasks​
Build mode is powerful, but Plan mode is the safer default for:
- unfamiliar code
- large refactors
- risky migrations
- changes with unclear scope
3. Add explicit permissions​
Do not leave real repositories on the fully permissive default if your team cares about guardrails.
Good starting idea:
edit:askbash:asktask:ask- external or web tools: restricted as needed
4. Put reusable behavior in .opencode/​
If a workflow repeats, move it out of chat history and into:
- a custom command
- a custom agent
- a skill
- a project config file
That is how OpenCode scales from "interesting tool" to "repeatable team workflow."
5. Separate concerns by agent​
Use different agents for:
- planning
- implementation
- review
- docs
- debugging
This is cleaner than trying to force one universal prompt to do everything well.
6. Use project config to stabilize the team experience​
Put the important defaults in opencode.json so every developer gets the same:
- model defaults
- permissions
- commands
- enabled providers
- MCP setup
10. Where OpenCode fits best​
OpenCode is especially strong when you want:
- an open-source terminal agent
- provider independence
- local model support
- shared repo-level customization
- a richer extension model than a minimal coding CLI
It is often a better fit than a simpler tool when your team wants to invest in:
- custom agent roles
- reusable slash commands
- skills and internal instructions
- MCP-heavy workflows
- policy and permission control
Compared with Aider​
OpenCode is generally more attractive when you want:
- a broader agent model
- more customization surfaces
- web/server/desktop options
- skill and plugin layering
Aider is often simpler if your priority is:
- a very git-centric loop
- tightly scoped file editing
- minimal conceptual overhead
Compared with vendor CLIs​
Compared with Claude Code or Codex CLI, OpenCode gives up some "single-vendor polish" in exchange for:
- more backend freedom
- more extensibility
- more local control
- easier reuse of cross-tool instruction assets
11. Recommendation​
OpenCode makes the most sense if you want a serious open coding agent platform, not just a prompt shell.
Use it when you want to standardize on:
- one terminal-native workflow
- many possible model backends
- project-local agent customization
- reusable internal commands, skills, and policy
If you only need quick AI edits in a git repo, a narrower tool may be enough. But if you want a coding agent that can grow into a team operating layer, OpenCode is one of the more compelling open-source options.