OpenCode — Getting Started

OpenCode is a terminal-based 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.

Installation

# Via npm
npm install -g opencode-ai

# Via Homebrew
brew install anomalyco/tap/opencode

# Verify
opencode --version

Provider Setup

OpenCode supports any OpenAI-compatible endpoint. Choose your provider:

Quick Setup — Common Providers

# 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-..."

Configure in ~/.config/opencode/opencode.json or opencode.json (project root):

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    },
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    },
    "deepseek": {
      "options": {
        "apiKey": "{env:DEEPSEEK_API_KEY}"
      }
    }
  }
}

Most providers are auto-detected from your exported API key — the provider block is only needed for custom endpoints or non-default options.

Pricing Plans

First Session

cd my-project
opencode

On first run, OpenCode prompts you to connect a provider. Type /connect, pick your provider, and follow the auth flow (browser OAuth or paste an API key). Then run /models to 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 (see above), OpenCode detects it automatically and you can skip /connect.

Essential Slash Commands

Plan mode isn't a slash command — press Tab in the TUI to switch between Build and Plan mode.

Session Management

Every session's full conversation history, file snapshots, and token usage are stored in a SQLite database at ~/.local/share/opencode/opencode.db. Find the path with opencode db path.

TUI Commands

CLI Commands

Continuing Past Work

# Continue the most recent session
opencode -c

# Continue a specific session by ID
opencode -s ses_312c8fd8bffe5DMWmNRPKKLvt3

# Fork a session (branch without modifying the original)
opencode --fork --continue

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

Project Configuration: AGENTS.md

Like Claude Code's CLAUDE.md, OpenCode reads AGENTS.md every session. Create it at your project root:

# 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)

Provider Selection Strategy

OpenCode's key advantage: switch providers mid-session with /provider. Debug with Sonnet, then switch to DeepSeek for less demanding work.

Related Pages

• Prompt Engineering in OpenCode — AGENTS.md patterns, /slash commands
• OpenCode Configuration Reference — opencode.json, MCP, skills
• Session History & Recovery — where sessions are stored and how to query them
• Tool Comparison — OpenCode vs Claude Code vs Gemini CLI vs Cursor vs Copilot
• OpenCode Guide (Blog) — In-depth setup and configuration walkthrough