OpenCode: A Terminal-Based Coding Agent with a Built-In Safety Split

What OpenCode Solves and Who It Is For

OpenCode is a terminal-based AI coding agent. It inspects repositories, edits files, runs commands, and connects to multiple model providers. The intended user is a developer who lives in the shell and wants an assistant that operates on the same files and processes they already manage. It is not a chat widget or an IDE plugin. It is a standalone executable that you invoke from a terminal, and it can act on the repository directly. The README positions it as "The open source AI coding agent," which is a broad claim, but the concrete value is the ability to delegate file edits and command execution to an agent without leaving the terminal. This suits solo developers, open source maintainers, and engineers who prefer keyboard-driven workflows over graphical interfaces.

The Build and Plan Agent Split

OpenCode's core design is the separation between two built-in agents, switchable with the Tab key. The build agent is the default and has full access. It is the full-access agent for development work, which is what you want for active development. The plan agent is read-only. It denies file edits by default and asks permission before running bash commands. This is a meaningful safety boundary. You can explore an unfamiliar codebase, ask questions, and draft a change plan without risking accidental modifications. The plan agent is ideal for understanding a new project or deciding what to change before switching to build mode. There is also a general subagent, invoked with @general, used internally for complex searches and multistep tasks. This split is not cosmetic. It gives you a low-risk mode for analysis and a high-access mode for execution, and the Tab toggle makes the transition quick.

Installation Paths and Their Trade-offs

The README lists many installation methods. The one-liner curl script is the fastest: curl -fsSL https://opencode.ai/v2/install | bash. Package managers are also covered: npm i -g @opencode/cli@latest, brew install anomalyco/tap/opencode-v2, and brew install opencode. The README notes that the tap formula is "always up to date" while the official brew formula is "updated less." That distinction matters if you need recent fixes. Arch users get sudo pacman -S opencode for the stable version and paru -S opencode-beta for the latest from the AUR. There is also mise use -g opencode and nix run github:anomalyco/opencode. The install script installs OpenCode to $HOME/.opencode/bin. The trade-off is that the curl pipe to bash model requires you to trust the script, while package managers give you a more auditable path but with varying freshness.

Desktop App: A Beta That Extends the Reach

OpenCode also ships a desktop application, marked as BETA. It is available for macOS (Apple Silicon and Intel), Windows, and Linux in .deb, .rpm, and .AppImage formats. The README points to opencode.ai/download for downloads. For macOS, you can use brew install --cask opencode-desktop. The beta status means you should expect rough edges. The terminal version is the primary interface, and the desktop app is an optional convenience. If you need a stable GUI, wait until the beta label is removed.

Configuration and Provider Flexibility

The README points to https://opencode.ai/v2/docs for configuration details, but it does not list specific config keys. What is clear is that OpenCode connects to multiple model providers. That means you are not locked into a single vendor. The exact list of providers and how to set API keys is not in the README, so you must consult the docs. The repository layout shows a TypeScript project with a packages directory, including packages/console/app, which suggests a web-based console component as well. The agent itself is likely configurable via a config file, but the README does not show one. The lack of explicit config examples in the README is a gap. A new user will need to visit the docs site to set up their provider, which adds friction compared to tools that include a sample config in the README.

Limitations and Wrong-Tool Cases

OpenCode is not the right tool if you need a fully audited, read-only analysis environment without any command execution. The plan agent asks permission before bash commands, but it still runs them after approval. If your security policy forbids any agent-initiated commands, this is a mismatch. Another limitation is the dependency on a terminal. Developers who prefer an IDE-integrated assistant will find the terminal interface awkward. The README also warns about version compatibility: "Remove versions older than 0.1.x before installing." This implies breaking changes in early versions, so upgrading from an old install may fail if you do not uninstall first. The desktop app is beta, so GUI users face instability. Finally, the multi-provider support is only as good as the provider's API. If your provider is not supported, you cannot use OpenCode at all until it is added. The README does not list supported providers, so you must verify this before adoption.

Alternatives: The Difference in Approach

A direct alternative is Aider, another terminal-based AI pair programmer. Aider focuses on git integration and edits files by making commits, which gives a natural undo mechanism. OpenCode's approach is different: it has a plan agent that is read-only and a build agent with full access. The Tab switch between agents is a distinct workflow. Another alternative is an IDE-based assistant like GitHub Copilot in VS Code. That tool lives inside the editor. OpenCode, by contrast, is a standalone agent that can execute bash commands in your terminal, which is a broader scope but also a higher risk. The choice depends on whether you want the agent to operate on your whole system or just the code in the editor. The README also mentions that projects using "opencode" in their name are asked to add a note that they are not affiliated, which shows the project cares about brand confusion but does not affect the tool's functionality.

Maintenance and License Implications

OpenCode is licensed under MIT, which means you can use, modify, and distribute it with minimal restrictions. The repository is not archived, and the last push was 2026-11-02, with recent releases v2.2.5, v2.2.4, and v2.2.3. The release cadence is active, with multiple releases in a single day, which suggests a fast-moving project. That has a maintenance cost: you need to track updates to get bug fixes and new features. The README's warning about removing old versions before installing indicates that upgrades are not always clean. The default branch is dev, which implies that the development branch is the primary line, and stable releases are cut from it. This is a common pattern but means the dev branch may have unstable changes. For production use, pin to a specific release version. The MIT license also means you can fork it if the project changes direction, but you must handle updates yourself. The maintenance burden is real: you must monitor releases and test upgrades, especially given the install method differences between the tap and the official brew formula.

Editorial conclusion

Adopt OpenCode if you work primarily in a terminal, want a local agent that can edit and execute without leaving the shell, and need a read-only planning mode to explore unfamiliar code before making changes. Do not adopt it if you require a fully GUI-based workflow or if your team standardizes on an IDE-integrated assistant. Before committing, verify that your preferred model provider is supported, test the plan agent's permission prompts on a sample repository, and confirm the install method matches your OS, since the brew formula and AUR package track different update cadences.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes