Skip to content
Get packs

Guide · Open source

How to use OpenCode: install it and work with its agents

Updated · written with AI from the project's own documentation and checked against our catalogue data

OpenCode is an open source AI coding agent that runs in your terminal and works on your existing software projects. This guide is for developers who are comfortable installing command-line tools. By the end you will know how to install OpenCode, how its built-in agents differ, and what to check before accepting changes it makes.

OpenCodeanomalyco/opencode · ★ 224k · MIT

Quick start

  1. 1Pick an install route. Choose npm, Homebrew or the curl script based on the tools you already have. Remove any versions older than 0.1.x first.
  2. 2Install the CLI. Run the install command for your chosen route, such as npm i -g @opencode/cli@latest.
  3. 3Open your project. Change into the project folder you want the agent to work on.
  4. 4Start with the plan agent. Switch to plan with the Tab key to explore the code read-only and ask for permission before any bash command.
  5. 5Switch to build for changes. When you are ready to make edits, switch to the build agent, which has full access for development work.
  6. 6Review every change. Read the diffs and commands the agent proposes before accepting them.

What OpenCode is and who it is for

OpenCode is described in its README as a terminal-based AI coding agent. It is built around reading and editing code, so it fits developers who want an agent working inside their terminal and existing projects.

It is a good match for people exploring an unfamiliar codebase, and for teams that want an MIT-licensed, inspectable agent rather than a closed product. It is not aimed at non-programmers, because the tool assumes development work.

  • Good fit: developers who live in the terminal and want an agent in their project.
  • Good fit: anyone reading code they did not write and wanting a read-only assistant.
  • Poor fit: non-programmers, or anyone who cannot review AI-generated changes before accepting them.

Install OpenCode with npm, Homebrew or curl

The README lists several install routes. The npm route needs npm, bun, pnpm or yarn. The Homebrew route needs Homebrew and works on macOS and Linux. The curl script installs OpenCode to $HOME/.opencode/bin.

The README also says to remove versions older than 0.1.x before installing.

  • npm, bun, pnpm or yarn: install the CLI globally.
  • Homebrew (macOS and Linux): use the anomalyco/tap formula.
  • curl script: pipes the official install script to bash.
npm i -g @opencode/cli@latest brew install anomalyco/tap/opencode-v2 curl -fsSL https://opencode.ai/v2/install | bash

Understand the build and plan agents

OpenCode includes two built-in agents that you switch between with the Tab key. The build agent is the default and has full access for development work. The plan agent is read-only and is meant for analysis and code exploration.

The plan agent denies file edits by default and asks permission before running bash commands. It is the safer choice when you want to understand code before changing it. There is also a general subagent for complex searches and multistep tasks, which you can call with @general in a message.

  • build: default, full-access agent for making changes.
  • plan: read-only, denies file edits by default, asks before bash commands.
  • general: subagent for complex searches; invoke with @general.

Use the desktop app (beta) carefully

OpenCode is also offered as a desktop application. The README marks it as BETA, so treat it as less stable than the terminal tool. Downloads are listed for macOS (Apple Silicon and Intel), Windows and Linux.

On macOS you can install the desktop app with Homebrew using a cask.

  • Download page: opencode.ai/download.
  • Linux packages listed: .deb, .rpm or .AppImage.
  • The README does not describe desktop app features beyond its download.
brew install --cask opencode-desktop

Configure OpenCode and find more help

The README points to the project documentation for configuration details. Its agents page is linked from the README as well. This guide only covers what the README itself describes, so check the docs for settings.

If you want to contribute, read the CONTRIBUTING.md file before opening a pull request.

  • Docs: opencode.ai/v2/docs.
  • Agents: opencode.ai/v2/docs/agents.
  • Community: Discord and X.com links are in the README.

What people use it for

  • Exploring an unfamiliar codebase with the read-only plan agent.
  • Making changes to an existing project with the build agent.
  • Asking a subagent to run complex searches through @general.
  • Using an MIT-licensed agent you can inspect in your own environment.

Frequently asked questions

Is OpenCode free?

OpenCode is released under the MIT licence, and its source is public on GitHub. The README does not list prices, so check the project's own pages for any paid offerings before assuming anything.

What do I need to install OpenCode?

For the npm route you need npm, bun, pnpm or yarn. For the Homebrew route you need Homebrew, which works on macOS and Linux. The curl script is another option listed in the README.

How do I install OpenCode with npm?

Run npm i -g @opencode/cli@latest. The README also lists bun, pnpm and yarn as alternatives for this route.

What is the difference between the build and plan agents?

The build agent is the default and has full access for development work. The plan agent is read-only, denies file edits by default and asks permission before running bash commands.

Is the OpenCode desktop app ready for daily use?

The README marks the desktop app as BETA. If you need a stable, fully supported desktop app, the README suggests waiting or choosing another tool.

How does OpenCode compare to Aider, Cline or Continue?

The README lists Aider, Continue, Cline and Goose as comparable projects but does not compare features. Try the tools on a small task in your own project to decide which fits your workflow.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

OpenCode suits developers who are comfortable with the terminal and package managers and want an MIT-licensed, inspectable AI coding agent. Use the read-only plan agent when exploring code, and review every change the build agent makes. Non-programmers, and anyone who needs a stable desktop app, should look at other options.

Install options & downloads