OpenCode Developer Guide: The Open Source AI Coding Agent with 160K Stars

Last updated: June 12, 2026

OpenCode crossed 160,000 GitHub stars in early 2026, making it the most popular open-source AI coding agent by a wide margin. Over 7.5 million developers use it monthly. The appeal is simple: model-agnostic, terminal-native, fully open source, and you own your data.

This guide covers what OpenCode is, how to install it, which models to use, and where it fits against commercial alternatives like Claude Code and Cursor.

What Is OpenCode?#

OpenCode is a terminal-based AI coding agent built by the team behind SST (now Anomaly). It runs locally on your machine, connects to 75+ AI providers, and gives you full control over which models process your code.

The core architecture:

• Terminal UI (TUI) built with Bubble Tea - a rich interactive interface in your terminal
• Multi-provider support - Anthropic, OpenAI, Google, AWS Bedrock, Azure, Groq, OpenRouter, and local models via Ollama
• LSP integration - Language Server Protocol feeds real compiler diagnostics back to the model after every edit
• Git-based undo/redo - every change is snapshotted, rollback with /undo
• MCP support - connect to Model Context Protocol servers for extended tool access
• Session persistence - conversations stored locally in SQLite, never transmitted

Unlike Claude Code (Anthropic-only) or Cursor (subscription-based IDE), OpenCode is MIT-licensed and model-agnostic. You bring your own API keys and pay only for the tokens you use.

Installation#

macOS and Linux#

The fastest path:

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

Or via package managers:

# Homebrew
brew install anomalyco/tap/opencode

# npm
npm i -g opencode-ai@latest

Windows#

# Scoop
scoop install opencode

Arch Linux#

sudo pacman -S opencode

Verify Installation#

opencode --version

You should see version 1.17.x or later (the current release as of June 2026 is v1.17.4).

Initial Setup#

After installation, configure your preferred AI provider:

opencode auth login

This launches an interactive flow to connect your API keys. OpenCode supports multiple simultaneous providers - you can switch models mid-session.

For manual configuration, create .opencode.json in your home directory or project root:

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "providers": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}"
    },
    "openai": {
      "apiKey": "${OPENAI_API_KEY}"
    }
  }
}

Environment variables work for API keys: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, etc.

Supported Models#

OpenCode connects to 75+ AI providers. The practical choices for coding:

Anthropic (Recommended for Most Work)#

OpenAI#

Google#

Local Models (Ollama)#

For local privacy (HIPAA, PCI DSS, air-gapped environments), Ollama models keep everything on your machine. The tradeoff: 70B-class models are needed for reliable tool-calling. Smaller models hallucinate function arguments.

Key Features#

Two Operating Modes#

Build Mode (default) - Full read/write access to files, command execution, codebase search. This is where most work happens.

Plan Mode - Read-only analysis. Use /plan to switch. The model analyzes your codebase and suggests changes without modifying files. Good for understanding unfamiliar code or reviewing proposals before execution.

LSP Integration#

OpenCode spawns Language Server Protocol servers and feeds compiler diagnostics back to the model after every edit. When the model introduces a TypeScript type error, it sees the error and self-corrects.

This is unique to OpenCode in 2026 - commercial tools like Claude Code do not have LSP integration for real-time error feedback.

Supported languages: TypeScript, Python, Rust, Go, C/C++, Java, and 18+ others.

Undo/Redo#

Every meaningful change creates a Git snapshot. No manual commits needed.

/undo    # Roll back the last change
/redo    # Reapply a reverted change

This is safer than trusting the model to "fix" a broken change - just revert and try a different approach.

Multi-Session Support#

Run parallel agent sessions on the same project:

# Terminal 1
opencode

# Terminal 2
opencode --session feature-auth

# Terminal 3
opencode --session refactor-api

Each session maintains its own conversation history and can work on different parts of the codebase simultaneously.

MCP Support#

Connect to Model Context Protocol servers for extended capabilities:

{
  "mcp": {
    "servers": [
      {
        "name": "filesystem",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
      }
    ]
  }
}

Recent v1.17.x updates added cwd configuration for workspace-relative MCP server paths.

Custom Commands#

Create reusable prompt macros as Markdown files in .opencode/commands/:

<!-- .opencode/commands/review.md -->
Review the code in {{file}} for:
- Security vulnerabilities
- Performance issues
- Type safety
- Error handling gaps

Provide specific line references and suggested fixes.

Use with /review file=src/api.ts.

Non-Interactive Mode#

Run OpenCode in scripts and CI/CD pipelines:

# Single prompt, text output
opencode -p "Add error handling to src/api.ts"

# JSON output for parsing
opencode -p "List all TODO comments" -f json

# Quiet mode (no spinner)
opencode -q -p "Fix the TypeScript errors in src/"

This enables automation workflows: pre-commit hooks, nightly refactors, automated test generation.

IDE Extensions#

OpenCode runs as a server that multiple frontends can connect to. Official extensions exist for:

• VS Code
• Cursor
• JetBrains IDEs (IntelliJ, PyCharm, WebStorm)
• Neovim
• Zed
• Emacs

The terminal TUI remains the primary interface - IDE extensions provide inline access without switching windows.

OpenCode vs Claude Code vs Cursor#

When to choose OpenCode:

• You want model flexibility and vendor lock-in avoidance
• You need local deployment for compliance (HIPAA, PCI DSS, government)
• You prefer terminal workflows over IDE integrations
• You want to pay per-token instead of monthly subscriptions
• You value open source and want to inspect/modify the code

When to choose Claude Code:

• You want the tightest Anthropic model integration
• You prefer managed subscriptions over API key management
• Your team standardizes on Claude models anyway

When to choose Cursor:

• You want an IDE-first experience with AI built in
• Visual diff workflows matter more than terminal speed
• You want autocomplete and agent features in one tool

Performance Note#

Builder.io testing showed Claude Code completed tasks in 9 minutes 9 seconds versus OpenCode at 16 minutes 20 seconds - OpenCode was 78% slower. However, OpenCode produced more thorough output (94 tests versus 73). The LSP integration adds overhead but catches more errors.

OpenCode Go and OpenCode Zen#

Beyond the free open-source tool, the OpenCode team offers two paid tiers:

OpenCode Go ($5 first month, $10/month) - Access to curated open-source models including Kimi K2, Qwen3, MiniMax, GLM-5, and MiMo. Good for developers who want capable models without managing API keys.

OpenCode Zen (pricing varies) - Premium tier with benchmarked model routing. The system automatically selects the best model for each task type.

These are optional - the core OpenCode tool remains free and works with any API key you provide.

The OpenCode / Crush Split#

In 2025, the original OpenCode repository was maintained by Charm. After a dispute over direction, the project split:

• OpenCode - Maintained by SST/Anomaly (Dax Raad and Adam Doty). This is the active fork with 160K+ stars. The codebase was rewritten in TypeScript using Bun.
• Crush - Charm's continuation. Polished TUI with signature Charm aesthetics, but smaller community.

The SST/Anomaly version at github.com/sst/opencode is what most developers mean when they say "OpenCode" in 2026.

Getting Started Workflow#

1. Install OpenCode:

   Terminal

   Copy

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

2. Configure your provider:

   Terminal

   Copy

   export ANTHROPIC_API_KEY="your-key"
   opencode auth login
   

3. Navigate to a project:

   Terminal

   Copy

   cd your-project
   opencode
   

4. Start with Plan Mode to understand the codebase:

   Code

   Copy

   /plan
   Explain the architecture of this project
   

5. Switch to Build Mode for changes:

   Code

   Copy

   /build
   Add input validation to the login form
   

6. Use /undo if something breaks:

   Code

   Copy

   /undo
   

FAQ#

What is OpenCode?#

OpenCode is an open-source, terminal-native AI coding agent that connects to 75+ AI providers. It runs locally, stores conversations in SQLite, and gives you full control over which models process your code. The MIT license means you can inspect, modify, and self-host the entire system.

Is OpenCode free?#

Yes. The core software is free and open source. You pay only for the AI models you use - either through API keys (Anthropic, OpenAI, etc.) or by running local models via Ollama at zero marginal cost.

How does OpenCode compare to Claude Code?#

OpenCode supports 75+ model providers versus Claude Code's Anthropic-only approach. OpenCode has LSP integration for real-time compiler feedback. Claude Code has tighter Anthropic model optimization and managed subscriptions. OpenCode is open source; Claude Code is proprietary.

Can I use OpenCode with local models for privacy?#

Yes. Connect Ollama with models like Qwen3 72B or Llama 3.3 70B. All processing stays on your machine. This is the path for HIPAA, PCI DSS, and air-gapped deployments. Smaller models (under 70B parameters) tend to hallucinate tool arguments.

What is the difference between OpenCode and Crush?#

Both descended from the same original project. OpenCode (maintained by SST/Anomaly) has 160K+ stars and is the active community standard. Crush (maintained by Charm) is a separate fork with different aesthetics. Most developers use the SST version.

Does OpenCode work in CI/CD pipelines?#

Yes. Use non-interactive mode: opencode -p "prompt" -f json. This enables automated refactoring, test generation, and code review in continuous integration workflows.

Which model should I use with OpenCode?#

For day-to-day coding: Claude Sonnet 4.6 or GPT-4.1. For complex multi-file refactors: Claude Fable 5 or GPT-5.5. For cost-sensitive work: Claude Haiku 4.5 or Gemini 2.5 Flash. For maximum privacy: Qwen3 72B via Ollama.

How do I switch models mid-session?#

Use the /model command or configure model switching in your .opencode.json. The provider-agnostic architecture means you can start with a fast model for exploration and switch to a more capable model for execution.

Continue Reading#

• Cactus Needle 2: The 14MB Agentic LLM That Runs on a Raspberry Pi 5
• Deploy From Your Coding Agent: Wire Railway''s MCP Server Into OpenCode
• DiffusionGemma: Google Bets Diffusion Can Make Text Generation 4x Faster
• Mellum2 Developer Guide: JetBrains' Open-Source Coding Model
• Perplexity Bumblebee: Developer Guide to the Open Source Supply Chain Scanner
• Ship a Remote MCP Server: Give Your Coding Agent Cloud Tools in an Afternoon
• OpenCode 2: How to Upgrade From v1 - what breaks in the v2 migration and a safe checklist
• Freebuff Review: The Free Coding Agent Paid for by Ads - what the ad-funded free tier includes and what its privacy policy says.

Sources#

• OpenCode Official Site
• OpenCode GitHub Repository (SST)
• OpenCode Changelog
• OpenCode Developer Guide - ssntpl.com
• What is OpenCode? - Nimbalyst
• OpenCode Deep Dive - sanj.dev
• Top CLI Coding Agents 2026 - Pinggy
• OpenCode Background Story - TechFundingNews