How to Use OpenCode: Complete Beginner Guide (2026)

OpenCode is an open-source terminal-based AI coding agent. It works similarly to Claude Code -- you type instructions in your terminal and AI writes, edits, and debugs your code. The key difference: OpenCode supports multiple AI providers (not just Anthropic), so you can switch between Claude, GPT-4, Gemini, and local models.

This guide covers installation, setup, your first task, and when OpenCode is the right tool.

In this guide:

• What OpenCode does
• Installation and setup (3 minutes)
• Your first OpenCode task
• Configuration and providers
• OpenCode pricing
• OpenCode vs Claude Code vs Gemini CLI

Related guides: How to Use Claude Code · How to Use Cursor AI · How to Use Gemini CLI · Claude Code vs OpenCode Comparison · All AI Coding Tool Comparisons

What OpenCode Does

OpenCode is a terminal AI agent that connects to your codebase and helps you build software. You type natural language instructions, and OpenCode:

• Reads your project files to understand your codebase
• Writes and edits code across multiple files
• Runs terminal commands (tests, builds, git)
• Debugs errors by reading logs and fixing code
• Supports multiple AI models -- Claude, GPT-4, Gemini, local models

The main advantage over Claude Code: you choose your AI provider. Not locked into Anthropic. You can use OpenAI for some tasks, Claude for others, and even run local models for privacy-sensitive work.

Installation and Setup

Prerequisites

• Node.js 18+ or Go 1.21+ (for building from source)
• An API key from at least one AI provider (Anthropic, OpenAI, or Google)
• A terminal

Step 1: Install OpenCode

# Using npm
npm install -g opencode

# Or using Go
go install github.com/opencode-ai/opencode@latest

Verify the installation:

opencode --version

Step 2: Configure Your API Key

OpenCode needs at least one provider API key. Set it as an environment variable:

For Anthropic (Claude):

export ANTHROPIC_API_KEY="sk-ant-your-key-here"

For OpenAI (GPT-4):

export OPENAI_API_KEY="sk-your-key-here"

For Google (Gemini):

export GEMINI_API_KEY="your-key-here"

You can set multiple keys and switch between providers during a session.

Step 3: Start Using OpenCode

cd your-project-folder
opencode

You'll see the prompt:

opencode>

Setup complete. Total time: about 3 minutes.

Your First OpenCode Task

Example 1: Understand Your Codebase

opencode> Analyze this project and tell me: what does it do, what's the tech stack, and how is it structured?

OpenCode reads your files and provides a comprehensive summary.

Example 2: Add a Feature

opencode> Add a /health endpoint to the Express server. It should return JSON with status, uptime in seconds, and memory usage.

OpenCode finds the server file, reads the existing structure, and adds the endpoint.

Example 3: Fix a Bug

opencode> The login form doesn't validate the email field. Users can submit without entering an email. Fix the validation and add an error message.

OpenCode locates the form component, reads the validation logic, and adds email validation.

Example 4: Switch Providers Mid-Session

opencode> Switch to GPT-4o for this task: Write a Python script that scrapes the top 10 HN stories and formats them as a Markdown table.

OpenCode uses the specified provider for this task. You can switch back to Claude or Gemini for the next one.

Configuration and Providers

Using a Config File

Create .opencode.json in your project root:

{
  "default_provider": "anthropic",
  "default_model": "claude-3.5-sonnet",
  "providers": {
    "anthropic": {
      "model": "claude-3.5-sonnet"
    },
    "openai": {
      "model": "gpt-4o"
    },
    "google": {
      "model": "gemini-2.5-pro"
    }
  }
}

When to Use Each Provider

Provider	Model	Best For	Cost
Anthropic	Claude 3.5 Sonnet	Complex reasoning, multi-file edits, writing	$3/M in, $15/M out
OpenAI	GPT-4o	General coding, fast responses	$2.50/M in, $10/M out
Google	Gemini 2.5 Pro	Large codebases (1M context), free tier	$1.25/M in, $10/M out
Google	Gemini 2.0 Flash	Quick tasks, cheapest option	$0.10/M in, $0.40/M out

Strategy: Use Claude for complex implementation work, GPT-4o for quick fixes, and Gemini for analyzing large files or when you want free usage.

OpenCode Pricing

OpenCode itself is free and open source. You pay only for the AI API calls you make.

Typical costs by provider:

Task Type	Claude Sonnet	GPT-4o	Gemini Pro	Gemini Flash
Simple question	$0.01	$0.008	$0.004	$0.001
Add a feature	$0.05-0.15	$0.04-0.12	$0.02-0.06	$0.005-0.02
Multi-file refactor	$0.10-0.30	$0.08-0.25	$0.04-0.12	$0.01-0.04
Full bug investigation	$0.05-0.20	$0.04-0.15	$0.02-0.08	$0.005-0.03

Monthly estimate: Most developers spend $3-8/month with regular use across providers.

For detailed cost calculations, see our AI cost calculator and our 200-task benchmark report.

OpenCode vs Claude Code vs Gemini CLI

Feature	OpenCode	Claude Code	Gemini CLI
Providers	Multiple (Claude, GPT, Gemini, local)	Anthropic only	Google only
Price	Free + API costs	Free + API costs	Free tier + API
Model switching	Yes, per task	No	No
File editing	Yes	Yes	Limited
Command execution	Yes	Yes	Limited
Open source	Yes	No	No
Context window	Depends on model	200K tokens	1M tokens
Best For	Flexibility, multi-provider	Highest quality coding	Free usage, large files

When to Choose OpenCode

• You want flexibility to use different AI providers for different tasks
• You want open-source software you can inspect and modify
• You use multiple AI APIs and want a unified terminal interface
• You want to switch models based on cost/quality trade-offs per task

When to Choose Claude Code

• You want the highest code quality and don't mind being locked into Anthropic
• You need autonomous multi-step execution with complex reasoning
• See our Claude Code beginner guide for the full tutorial

When to Choose Gemini CLI

• You want a completely free option with generous rate limits
• You need the 1M token context window for massive files
• See our Gemini CLI beginner guide for setup

Using All Three Together

Through Ivern Squads, you can coordinate OpenCode, Claude Code, and Gemini CLI in the same workflow:

1. Gemini agent processes the full codebase (1M context)
2. Claude Code agent implements the changes (highest quality)
3. OpenCode agent runs tests with GPT-4o (fast, cheap verification)

See our multi-agent coding setup guide and OpenCode tutorial for setup instructions.

Frequently Asked Questions

How do I install OpenCode?

Install with npm install -g opencode or go install github.com/opencode-ai/opencode@latest. You need Node.js 18+ or Go 1.21+. Then set at least one API key (Anthropic, OpenAI, or Google) as an environment variable. Run opencode in any project directory to start. Setup takes about 3 minutes.

Is OpenCode free?

Yes. OpenCode is free and open source. You pay only for the AI API calls: Claude ($3/M input), GPT-4o ($2.50/M input), or Gemini ($1.25/M input). You can use Google Gemini for free with generous rate limits. Most developers spend $3-8/month total.

Can OpenCode use multiple AI models?

Yes. OpenCode supports Anthropic (Claude), OpenAI (GPT-4), Google (Gemini), and local models. You can switch providers per task, configure defaults in .opencode.json, or set multiple API keys and choose which to use for each request.

How does OpenCode compare to Claude Code?

OpenCode supports multiple AI providers while Claude Code only works with Anthropic. Claude Code produces slightly higher quality code for complex tasks. OpenCode gives you flexibility to choose the best model for each task. For a detailed comparison, see our Claude Code vs OpenCode guide.

Does OpenCode work with Python projects?

Yes. OpenCode works with all programming languages and project types. It detects your tech stack automatically and adapts its suggestions. Python, JavaScript, TypeScript, Rust, Go, Java, and more are all supported.

Can I use local models with OpenCode?

Yes. OpenCode supports local models through Ollama or other local inference servers. This is useful for privacy-sensitive code, air-gapped environments, or when you want zero API costs. Quality is lower than Claude or GPT-4 but sufficient for many tasks.

Next Steps

1. Install OpenCode: npm install -g opencode
2. Set an API key from Anthropic, OpenAI, or Google AI Studio
3. Try it: cd your-project && opencode
4. Compare tools: OpenCode vs Claude Code · Claude Code vs Gemini CLI
5. Optional: Connect to Ivern Squads for multi-agent coordination

Related reading: How to Use Claude Code · How to Use Cursor AI · How to Use Gemini CLI · AI Cost Calculator · All AI Coding Tool Comparisons

Start building with AI agent squads -- free signup