OpenCode: 205K-Star Open-Source AI Coding Agent Runs Locally With 75+ Models

Why OpenCode Is Gaining Traction

The author recounts taking over a legacy Python project with 14 failing unit tests, broken fixtures, and outdated dependencies. Instead of spending half a day debugging manually, a colleague suggested OpenCode. In the project directory, the author launched OpenCode, used Plan mode to analyze the test pipeline and confirm a fix strategy, then switched to Build mode. The agent automatically read the tests directory, located issues in conftest.py, modified four fixture configurations, updated expired dependencies in requirements.txt, ran tests for verification, and passed all cases in 4 minutes 32 seconds.

Unlike simple code completion, OpenCode acts as a full engineer agent: it understands the entire repository, reads and writes files, executes commands, runs tests, and self-debugs fixes.

Market Landscape and OpenCode's Position

AI coding tools split into two camps:

Closed-source: Claude Code, Codex CLI, Cursor — powerful but vendor-locked; sensitive code must upload to third-party servers; private deployment restricted.

Open-source: Most only do code completion, lack full agent execution, have cumbersome configuration, poor multi-model adaptation.

OpenCode fills the gap: MIT-licensed, no model-vendor binding, supports local models offline, client-server architecture, four interaction forms (terminal TUI, desktop app, web UI, VS Code/Cursor plugin), code context processed locally without cloud upload. GitHub stars reach 205K, monthly active developers exceed 16 million, making it the most mature open-source coding agent project.

Note: OpenCode ≠ Copilot alternative. Copilot is Tab autocomplete; OpenCode is an agent that receives tasks, autonomously analyzes projects, edits files, runs commands, debugs bugs — like a junior engineer sitting beside you.

Core Architecture

Dual-Core Agents (Tab Key Toggle)

Build (Executor, default mode): Full permissions — modify files, execute shell commands, install dependencies, run tests. Suited for implementing confirmed solutions.

Plan (Planner, read-only mode): File modifications disabled by default; bash commands prompt for confirmation. Designed for exploring unfamiliar codebases, architecture analysis, writing proposals, risk assessment, code review.

Best-practice workflow: Tab→Plan → analyze project, output plan/TODOs/risk points → human reviews plan, gives feedback iterates → Tab→Build → execute confirmed changes.

Additional built-in sub-agent: @general — invoke within a message to handle complex retrieval and multi-step tasks.

Client-Server Architecture (Key Design Highlight)

The backend service runs locally; TUI terminal, desktop app, browser web, IDE plugins all act as frontend clients connecting to the local service.

Service runs on the machine; all code stays local.

Phone browser can access web UI to remotely operate code projects on the home computer.

One service, multiple terminals simultaneously join the same session.

Hard-Core Capabilities

Reads entire codebase, understands file dependencies, monorepo multi-package architecture.

Directly edits project files, executes dev commands, lint, unit tests, auto-fixes errors.

Built-in LSP (Language Server Protocol) provides semantic code info to the LLM.

75+ LLM providers: OpenCode Zen free models, OpenAI, Anthropic, Gemini, DeepSeek, MiniMax, plus Ollama local models for offline runs.

Native MCP (Model Context Protocol) support for GitHub, databases, browser automation, etc.

Fine-grained permission sandbox: allow/ask/deny control over shell, file edits, external directories.

Session management, session branching (fork), session export to Markdown, session sharing links.

Deep Git integration: /undo rolls back file changes together; PR review, commit change auditing.

Cross-Platform Installation Guide

Prerequisites: Uninstall 0.1.x first (path conflicts cause errors). Node.js ≥ 18.0.

Method 1: NPM Global Install (Universal, Windows Preferred)

# Install
npm install -g opencode-ai@latest

# Verify version
opencode -v

# Uninstall
npm uninstall -g opencode-ai

Windows users: configure npm mirror for speed:

npm config set registry https://registry.npmmirror.com

Method 2: macOS/Linux One-Liner curl

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

Homebrew (macOS recommended, fastest updates):

brew install anomalyco/tap/opencode

Windows Package Managers

# Scoop
scoop install opencode

# Chocolatey
choco install opencode

Desktop Client (Beta)

Download from GitHub Releases: https://github.com/anomalyco/opencode/releases

Windows: opencode-desktop-windows-x64.exe macOS Apple Silicon: opencode-desktop-darwin-aarch64.dmg Linux: deb/rpm/AppImage

Docker One-Liner

docker run -it --rm ghcr.io/anomalyco/opencode

Verify Installation

# View help
opencode --help

# Start terminal TUI (run inside your project directory)
opencode

# Start web service, browse http://127.0.0.1:4096
opencode web

Critical pitfall: VS Code OpenCode plugin requires global opencode-ai installed first ; plugin alone fails because it depends on the local CLI service.

Configuration: Model Access, Permission Control, MCP Extensions

4.1 Connect LLMs

Two ways:

TUI command /connect, pick provider, enter API Key.

Environment variables: ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.

OpenCode Zen includes free models — no key needed. In TUI, /models switches models; those tagged Free are free. Model format: provider/modelId, e.g., opencode/deepseek-v4-flash-free, openai/gpt-4o-mini.

4.2 Project Initialization ( AGENTS.md )

Run /init in project root. Auto-generates AGENTS.md, commit to Git. Agent reads this file to understand project conventions, tech stack, coding standards; teams can codify project-specific agent rules.

4.3 Permission Sandbox ( opencode.json )

Config path: ~/.config/opencode/opencode.json. Fine-grained control over agent actions to prevent accidental deletions.

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "bash": {
      "*": "ask",
      "git *": "allow",
      "rm -rf *": "deny"
    },
    "edit": {
      "*": "ask",
      "docs/**/*.md": "allow"
    }
  }
}

Permission values: allow (auto-approve), ask (prompt before execute), deny (block).

4.4 MCP Tool Integration Example

MCP extends OpenCode to call external tools like GitHub, databases:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "environment": {"GITHUB_TOKEN": "ghp_xxx"}
    }
  }
}

Practical Usage Guide

Enter project, run opencode to start TUI.

Three Core Symbols

@ — reference file: @src/auth/index.ts explain auth logic — auto-loads file context, no copy-paste.

! — execute shell: !git log --oneline -10 — command output fed into conversation context.

/ — slash commands, all operations entry point.

Frequent Slash Commands

/agents

— Switch Build/Plan agent (equiv. Tab) /connect — Configure LLM provider API Key /models — View/switch LLMs /init — Generate project AGENTS.md /new — Start fresh session /undo — Undo last turn, roll back file changes (requires Git) /review — Git code review, audit commit/PR changes /sessions — Switch historical sessions /export — Export session as Markdown /compact — Compress session, reduce token usage /thinking — Toggle model reasoning block display /undo prerequisite: project must be a Git repo; relies on Git snapshots to roll back file changes.

Common Shortcuts

Tab

: Build ↔ Plan switch Esc: Interrupt running agent task Ctrl+X Q: Exit TUI Enter: Send message; Shift+Enter: New line

Non-Interactive Mode (Script/CI Invocation)

Run tasks without entering TUI:

# Direct task
opencode run "Refactor auth module, add JSDoc comments"

# With file input
opencode run "Review config risks" -f config.yaml

# Resume last session
opencode -c

# Session fork: branch from history without polluting original
opencode -c --fork

Web UI Usage

# Local access
opencode web

# Allow LAN devices (phone browser) to connect
opencode web --hostname 0.0.0.0

Access at:

http://127.0.0.1:4096

Side-by-Side Comparison

Open-source license: OpenCode MIT fully open; Claude Code, Codex CLI, Cursor closed.

Model binding: OpenCode 75+ providers, local Ollama; Claude Code Claude series only; Codex CLI OpenAI only; Cursor multi-model.

Run forms: OpenCode TUI, Desktop, Web, IDE plugin; Claude Code terminal TUI; Codex CLI terminal TUI; Cursor IDE editor.

Local offline models: OpenCode full support; Claude Code no; Codex CLI limited; Cursor no.

Private deployment: OpenCode official enterprise support; others no or SaaS only.

MCP protocol: OpenCode native full support; Claude Code supported; Codex CLI weak; Cursor supported.

Fine-grained permission sandbox: OpenCode shell/file/dir granularity; others basic or weak.

Cost: OpenCode pay for chosen model, free Zen models; Claude Code Anthropic billing; Codex CLI OpenAI billing; Cursor subscription from $20.

GitHub Stars: OpenCode 205K; others no public repo or closed product.

Selection Advice

Want ultimate Claude experience, budget ok, don't mind closed-source → Claude Code.

Heavy OpenAI user, want native GPT feel → Codex CLI.

Prefer IDE autocomplete as main, light agent as supplement → Cursor.

Enterprise sensitive code, need private deploy, switch any model, local offline, modify source → OpenCode.

Pitfalls & Avoidance Checklist

VS Code plugin alone fails — must globally install opencode-ai first . /undo relies on Git; non-Git repos won't roll back files.

Uninstall 0.1.x before new version; PATH corruption otherwise. .env, .env.* default denied (protect secrets); other sensitive files need manual deny in permission config.

Windows: curl|bash install invalid; use NPM, Scoop, Choco.

Web UI default OPENCODE_SERVER_PASSWORD empty — no password; set password if exposing on LAN.

Model format must be provider/modelId; wrong format throws ProviderModelNotFoundError.

Post-upgrade unknown config keys cause empty model list — delete invalid keys, restart.

Plan mode is default read-only but permissions can be manually opened; don't treat as absolute safety barrier.

Target & Non-Target Audiences

✅ Very Suitable For

Individuals/teams sensitive to code privacy, unwilling to upload business code to third parties.

Developers wanting free model switching plus local Ollama offline runs.

Developers working daily in terminal/Neovim environments.

Teams needing private deployment, custom agent logic, custom workflows.

Those onboarding large unfamiliar repos, needing agent-assisted exploration, review, refactor.

❌ Less Suitable For

Only want out-of-the-box Tab autocomplete, zero command-line interaction.

Zero CLI basics, unwilling to learn TUI operation.

Seek plug-and-play IDE experience, no desire to configure API keys/permissions.

Summary

OpenCode isn't trying to kill Claude Code; it gives developers another choice.

Closed-source tools are capable but exact a price: vendor lock-in, data egress, unauditable internals. OpenCode returns three rights to developers: model choice, runtime environment choice, code data control .

It's not perfect — higher entry barrier than typical IDE plugins, requires understanding agent modes and permission config. But for privacy-conscious, multi-model tinkerers, terminal power users, and private-deployment teams, it's currently the best open-source coding agent in the ecosystem.

AI won't replace programmers, but programmers who don't leverage AI will fall behind. Tools are amplifiers; architectural thinking and business judgment remain human.

Project URL: https://github.com/anomalyco/opencode