opencode Guide: Open Source AI Coding Agent Setup, Models, and Claude Code Comparison

opencode is an open source AI Coding Agent from anomalyco. Its positioning is straightforward: give developers a programmable, extensible coding assistant in the terminal that can connect to multiple model providers.

If you compare it with Claude Code and Codex, all three solve the same broad problem: bringing AI into real codebases so it can understand context, edit files, run commands, and execute tests. But their product directions are different.

opencode emphasizes open source, multi-model support, and a terminal TUI. Claude Code emphasizes Anthropic’s model ecosystem and local engineering collaboration. Codex is OpenAI’s AI coding agent, available through the terminal, IDEs, the Codex app, and cloud tasks.

Who opencode Is For

opencode is a better fit for these kinds of developers:

• People who want to complete code changes, project analysis, and engineering tasks in the terminal.
• People who do not want their AI Coding Agent tied to a single model provider.
• People who prefer open source tools and want to audit, extend, or build on top of them.
• People already comfortable with Neovim, TUIs, and command-line workflows.
• People who want to eventually drive the same coding agent remotely through a desktop app, mobile app, or other clients.

Its point is not to create another chat window, but to put AI coding capability inside the terminal and project directories developers already use.

Installation

The official README provides several installation methods.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

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

# npm
npm i -g opencode-ai@latest

# Windows
scoop install opencode
choco install opencode

# macOS and Linux
brew install anomalyco/tap/opencode
brew install opencode

# Arch Linux
sudo pacman -S opencode
paru -S opencode-bin

# Other methods
mise use -g opencode
nix run nixpkgs#opencode

The official README also recommends removing versions older than 0.1.x before installing to avoid problems caused by older remnants.

The installation script chooses the installation directory by priority:

1. $OPENCODE_INSTALL_DIR
2. $XDG_BIN_DIR
3. $HOME/bin
4. $HOME/.opencode/bin

If you need to specify a path, use:

1
2

OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

The Desktop App Is Still Beta

In addition to the command-line tool, opencode also provides a desktop app, currently marked as Beta. It can be downloaded from GitHub Releases or opencode.ai/download.

The desktop app covers these platforms:

macOS and Windows users can also install the desktop app through package managers.

1
2
3
4
5
6

# macOS
brew install --cask opencode-desktop

# Windows
scoop bucket add extras
scoop install extras/opencode-desktop

Two Built-In Agent Modes

opencode includes two built-in Agents, switchable with the Tab key.

build is the default mode. It has full development permissions and is suitable for editing code directly, running commands, and moving engineering tasks forward.

plan is read-only mode. It is better for analyzing unfamiliar codebases, understanding project structure, and planning changes. It denies file edits by default and asks before running bash commands.

opencode also includes a general subagent for complex searches and multi-step tasks. Users can invoke it by typing @general in a message.

This design is practical: use plan to understand the project before acting, then switch to build when code needs to change. For large repositories, separating read and write permissions helps reduce mistakes.

What Is Codex?

Codex is OpenAI’s AI coding agent for helping developers write code, review code, fix bugs, and ship engineering tasks.

Unlike a simple code completion tool, Codex is closer to an Agent that can operate on a codebase. It can pair with you in local tools, and it can also take delegated tasks in the cloud. OpenAI’s official materials describe Codex as available through multiple surfaces, including CLI, IDEs, the Codex app, and ChatGPT/Codex cloud workflows.

For developers, Codex has several important traits:

• It can read codebases, edit files, run commands, and execute tests.
• It supports multiple interfaces, including terminal, IDE, app, and cloud.
• It fits bug fixing, feature work, refactoring, migrations, code review, and test generation.
• It is more closely tied to OpenAI accounts, models, and the Codex product ecosystem.
• Cloud tasks are useful for running multiple well-scoped engineering tasks in parallel.

If opencode is more like an open terminal agent framework, Codex is more like a full AI coding workbench from OpenAI: local pairing, cloud delegation, and longer engineering workflows for teams.

Core Differences

opencode, Claude Code, and Codex are all AI coding tools, but the choice becomes clearer if you look at these dimensions.

In short, opencode is about openness and replaceability, Claude Code is about the Claude ecosystem and local engineering agents, and Codex is about the OpenAI ecosystem and multi-surface collaboration.

How It Differs From Claude Code

opencode’s official FAQ directly compares it with Claude Code. The two are similar in capability, but the main differences are these.

First, opencode is a 100% open source project, hosted on GitHub and released under the MIT license.

Second, opencode is not tied to a single model provider. It recommends models provided through OpenCode Zen, but it can also work with Claude, OpenAI, Google, or local models. For developers, this means that when model cost, capability, or availability changes, you are not locked into one platform.

Third, opencode includes optional LSP support. For code completion, navigation, diagnostics, and project understanding, LSP is a very important foundation.

Fourth, opencode emphasizes TUI. It is built by Neovim users and the creators of terminal.shop, so the product focus is clearly on the terminal experience.

Fifth, opencode uses a client/server architecture. That means opencode can run on your computer while being controlled in the future by a TUI, desktop app, mobile app, or other clients. The TUI is only one possible frontend.

When to Choose opencode, Claude Code, or Codex

If you already use Claude Code or Codex, opencode does not have to replace them immediately. A better way to think about it is that opencode provides an open, model-replaceable, terminal-first option.

Consider opencode first when:

• You want your AI coding tool to be as open source as possible.
• You do not want your workflow tied to one model provider.
• You want to test Claude, OpenAI, Google, or local models with the same tool.
• You like TUI workflows and do not want a desktop or web app to interrupt your main workflow.
• You care about the remote-control potential of a client/server architecture.

Consider Claude Code first when:

• You mainly use Claude models.
• You care about long context, code understanding, and complex engineering task collaboration.
• You want to keep moving edits, tests, and refactors forward in a local repository.
• You trust Anthropic’s default Claude Code product experience.

Consider Codex first when:

• You already use ChatGPT or the OpenAI account ecosystem.
• You want one coding agent across terminal, IDE, desktop app, and cloud tasks.
• You want to delegate well-scoped bug fixes, feature work, migrations, or test generation to the cloud in parallel.
• You need code review, background tasks, team collaboration, and multi-Agent workflows.

If you care more about an official end-to-end experience, default model configuration, enterprise management, and ready-made integrations, Claude Code or Codex may be easier. If you care more about control, openness, and being provider-agnostic, opencode is worth watching.

Things to Note

opencode, Claude Code, and Codex are all moving quickly. GitHub releases, installation commands, desktop app file names, model availability, and plan access can all change. Before installing or choosing a tool, check the official README, documentation, and release pages.

Also, opencode’s desktop app is still marked as Beta, so it should not be treated as the default stable production tool. For everyday engineering tasks, the terminal version is still the main entry point.

From a tooling trend perspective, opencode represents the open-toolchain direction for AI Coding Agents: replaceable models, replaceable clients, and an open core agent capability. Codex and Claude Code are closer to model companies turning coding agents into complete product surfaces. For developers, both directions will likely coexist for a long time.

A practical Cursor, Claude Code, and Codex workflow

Daily Workflow

Step 1: Cursor Builds Context

In Cursor:

1. find the entry file;
2. inspect related modules;
3. confirm the edit scope.

Prompt:

1

这个功能的入口在哪里？相关文件有哪些？先不要修改代码。

Cursor is good for building a human-visible map.

Step 2: Claude Code Implements

Give Claude Code the scope found in Cursor:

1
2
3
4

根据这些文件实现功能 X。
范围限制在 src/api 和 src/components/Checkout。
先给计划，再改代码。
完成后运行 pnpm test -- Checkout。

Claude Code plans, edits, runs tests, fixes failures, and reports actual changes.

For large tasks, make it stop by phase instead of doing everything.

Step 3: Codex Reviews Independently

After Claude Code finishes:

1
2
3

请只读审查当前改动。
重点检查 bug、回归风险、权限边界、测试缺口和不必要的重构。
不要修改文件。

Codex should return findings, not a generic summary. If there are no high-risk issues, it should say so clearly.

If you use a plugin that calls Codex from Claude Code, you can put Codex inside the Claude Code workbench. Tutorial: /en/2026/07/06/codex-plugin-cc-claude-code-codex-plugin/.

Step 4: Human Finishes in Cursor

Return to Cursor:

• inspect diff;
• adjust naming;
• polish UI details;
• check imports;
• remove unnecessary comments;
• decide whether to commit.

AI can do a lot of work, but final shape and tradeoffs should still be reviewed in the IDE.

Three Example Task Splits

Production Bug

Prompt for Claude Code:

1
2
3

Claude Code：请只围绕订单金额计算错误排查。
先找相关测试和计算函数，不要重构无关模块。
修复后运行最小相关测试。

Prompt for Codex:

1
2
3

Codex：请审查当前 diff。
重点看金额精度、边界条件、旧订单兼容和测试覆盖。
只读，不修改。

New Feature

Codex can first review the plan without editing:

1
2
3

请根据当前代码库提出实现方案。
列出涉及文件、数据流、测试点和风险。
不要修改文件。

Large Refactor

Ask for read-only impact analysis first:

1
2
3

先做只读影响面分析。
列出必须改、可能改、不建议动的文件。
不要修改代码。

For long tasks, record state so dangerous commands are not repeated after interruption. See: .

Do Not Let Three Tools Write the Same Files

The biggest pitfall is concurrent writing:

• Cursor changes a component;
• Claude Code refactors the same component in terminal;
• Codex edits the same feature in another worktree;
• merge conflicts become unclear.

Stable rules:

1. Only one tool owns write access to the same files at a time.
2. Other tools perform read-only review or planning.
3. Use Git branches or worktrees for parallel tasks.
4. Check git status --short after each phase.
5. Humans confirm diff before merging.

If you truly need parallel work, split by module.

Rule Files

Use layered rule files:

1
2
3
4
5
6
7

repo/
  AGENTS.md
  CLAUDE.md
  .cursor/
    rules/
  docs/
    ai-workflow.md

Avoid conflicting rules. Put common rules in one place and tool-specific differences separately. Write dangerous commands, forbidden paths, and test commands clearly.

For codebase memory choices, see: .

Reusable Workflow Template

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# AI Coding Workflow

## Tool Roles

- Cursor: code reading, local edits, UI tweaks, final diff review.
- Claude Code: terminal tasks, implementation, debugging, running tests.
- Codex: planning, independent review, long-running tasks, parallel worktrees, reusable skills.

## Rules

- Only one tool writes to the same files at a time.
- Use read-only review before large refactors.
- Run `git status --short` before and after AI changes.
- Do not delete, move, or overwrite files without listing paths first.
- Use Codex for independent review before commit.
- Use Cursor for final human-facing diff inspection.

Short rules are enough if they affect real behavior.

When to Use Only One Tool

Use only Cursor for CSS tweaks, types, reading a function, UI component changes, and human-controlled diffs.

Use only Claude Code for failing tests, terminal reproduction, medium implementation, and command-output iteration.

Use only Codex for background tasks, cloud issue work, review findings, adversarial design review, or turning repeated flows into Skills.

Use all three for medium and large tasks, not every tiny edit.

References

• Codex CLI - OpenAI Developers
• Custom instructions with AGENTS.md - OpenAI Developers
• Codex in ChatGPT - OpenAI
• Claude Code overview - Anthropic Docs
• Claude Code product page - Anthropic
• Cursor Agent search docs
• Cursor official site

References

• opencode GitHub: https://github.com/anomalyco/opencode
• opencode official site: https://opencode.ai
• opencode docs: https://opencode.ai/docs
• opencode Releases: https://github.com/anomalyco/opencode/releases
• OpenAI Codex: https://openai.com/codex/
• Using Codex with your ChatGPT plan: https://help.openai.com/en/articles/11369540-codex-in-chatgpt
• OpenAI Codex CLI Getting Started: https://help.openai.com/en/articles/11096431-openai-codex-ci-getting-started