OpenCode — Getting Started

OpenCode is an AI coding agent that works with 75+ LLM providers. Unlike Claude Code (Anthropic-only) or Gemini CLI (Google-only), OpenCode lets you choose your model, pay what you want, and customize every aspect of the agent.

OpenCode 2 runs the agent as a shared background service. The terminal UI, web client, and desktop app all connect to the same server, so sessions and approvals stay in sync across them.

Installation

# Install script (recommended)
curl -fsSL https://opencode.ai/v2/install | bash

# Via npm
npm install -g @opencode/cli

# Via Homebrew
brew install anomalyco/tap/opencode-v2

# Verify
opencode --version

The npm package uses a postinstall script to select the native binary for your platform. With Bun or pnpm, allow the script explicitly:

bun install -g --trust @opencode/cli
pnpm add -g --allow-build=@opencode/cli @opencode/cli

Arch Linux users can install opencode-beta from the AUR (paru -S opencode-beta). Windows package managers are not supported; use the standalone binary from the download page.

Upgrading

opencode upgrade

If you are still on OpenCode 1, upgrade explicitly with opencode upgrade --major. V1 installs stay on the 1.x release line and are never offered 2.x as a routine update.

Provider Setup

Run /connect in the TUI, choose a provider, and complete the auth flow. Then pick a model with /models. Credentials are stored in ~/.local/share/opencode/auth.json.

Most providers can also be detected from environment variables:

# Anthropic (via API key)
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI
export OPENAI_API_KEY="sk-..."

# Google Gemini
export GOOGLE_API_KEY="..."

# DeepSeek (95% cheaper than Anthropic for coding)
export DEEPSEEK_API_KEY="sk-..."

# OpenRouter (300+ models, one API key)
export OPENROUTER_API_KEY="sk-or-..."

To configure a custom endpoint, add a providers block to ~/.config/opencode/opencode.jsonc or the project's opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-5-5",
  "providers": {
    "anthropic": {
      "settings": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    },
    "deepseek": {
      "settings": {
        "apiKey": "{env:DEEPSEEK_API_KEY}"
      }
    },
    "local": {
      "name": "Local server",
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "http://127.0.0.1:1234/v1"
      },
      "models": {
        "coder": {
          "modelID": "model-name-on-server"
        }
      }
    }
  }
}

Ollama, LM Studio, and vLLM are discovered automatically when they run on their default ports. Prefer /connect and /models over hand-editing provider blocks unless you need a custom endpoint.

Pricing Plans

Go is optional and works like any other provider: subscribe in the Console, copy the API key, then run /connect and select OpenCode Go.

First Session

cd my-project
opencode

On first run, connect a provider and choose a model:

> /connect
> Select a provider (Anthropic, OpenAI, DeepSeek, Google, OpenRouter...)
> Enter your API key or sign in via your browser

> /models
> Select the model to use for this session

If you exported your provider's API key, OpenCode detects it automatically and you can skip /connect.

Prompt basics

Essential Slash Commands

If your build does not include an /init command, create AGENTS.md yourself, or ask the agent to inspect the repository and write one.

Plan Mode vs Build Mode

OpenCode ships two primary agents:

• Build (build) — the default coding agent. It reads, writes, and edits files and runs commands within your permission rules.
• Plan (plan) — explores and plans without editing normal project files. Shell commands remain permission-controlled.

Press Shift+Tab to cycle agents, or run /agents. Each agent can have its own model and permissions; define custom agents in .opencode/agents/<name>.md or under agents in opencode.jsonc.

Session Management

Every session's conversation history, file snapshots, and token usage are stored in a local SQLite database. Find the exact path with:

opencode debug paths db

The default is ~/.local/share/opencode/opencode.db.

CLI Commands

Continuing Past Work

# Continue the most recent session
opencode run --continue "Now add tests"

# Continue a specific session by ID
opencode run --session ses_312c8fd8bffe5DMWmNRPKKLvt3 "Check edge cases"

# Pick up interactively, then choose the session with /sessions
opencode

For advanced querying — searching conversations by keyword, tracing tool-call sequences, auditing model costs — see Session History & Recovery.

Project Configuration: AGENTS.md

OpenCode reads AGENTS.md every session. Put it at the project root or next to the code it governs:

# AGENTS.md

## Commands
- `npm run dev` — Start development server at localhost:3000
- `npm run build` — Production build with type checking
- `npx vitest run` — Run all tests
- `npx eslint .` — Lint check

## Project Architecture
- Next.js 14 with App Router and React Server Components
- TypeScript strict mode with path alias @/
- SQLite via better-sqlite3 — no ORM, raw SQL
- Zero API dependencies for now

## Code Style
- Use async/await in server components for data fetching
- Extract business logic from components into lib/ immediately
- Tests go next to the file they test (co-location)

V2 discovers the global ~/.config/opencode/AGENTS.md and every AGENTS.md from the workspace toward home. It does not fall back to CLAUDE.md.

Provider Selection Strategy

Related Pages

• OpenCode Configuration Reference — providers, permissions, MCP, skills, and plugins
• Prompt Engineering in OpenCode — AGENTS.md conventions and prompt patterns
• Session History & Recovery — query the local database
• MCP Setup in OpenCode — step-by-step MCP configuration