How to Use OpenCode: Beginner Guide to the Open-Source AI Coding Agent (2026)

How to Use OpenCode: Complete Beginner Guide (2026)

Setup time: 3 minutes. OpenCode is a free, open-source AI coding agent that runs in your terminal. You tell it what to build, and it reads your code, makes edits, runs tests, and delivers results. This guide covers installation, configuration, and your first 5 tasks.

You need two things: a terminal and an API key from Anthropic, OpenAI, or Google. No subscription. No credit card. You pay the API provider directly at $2-8/month for typical usage.

Related: OpenCode vs Aider Comparison · OpenCode Full Review · Claude Code vs OpenCode · Cursor vs OpenCode · Best BYOK AI Platforms · Best Free AI Coding Assistants · OpenCode Alternatives · AI Coding Assistants Pricing · All Tutorials

What You Need Before Starting

You do not need a subscription. OpenCode is free software. You bring your own API key (BYOK) and pay wholesale API rates.

Step 1: Install OpenCode (2 minutes)

npm install -g opencode-ai

Verify the installation:

opencode --version

If you see a version number, you are ready. If not, make sure Node.js 18+ is installed:

node --version  # Should be v18 or higher

No Node.js? Install it from nodejs.org or use nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20

Step 2: Get an API Key (1 minute)

OpenCode works with any of these providers:

For beginners, we recommend Anthropic (Claude Sonnet 4) because it produces the most reliable code. Create an account, generate an API key, and copy it.

Step 3: Launch OpenCode (30 seconds)

Navigate to your project directory and start OpenCode:

cd your-project
opencode

On first launch, OpenCode walks you through provider setup. Paste your API key when prompted. The whole process takes under 30 seconds.

Your API key is stored locally in ~/.config/opencode/config.json. It never leaves your machine.

Step 4: Your First Task

Type a natural language instruction in the OpenCode prompt:

> Add a REST API endpoint for creating users with input validation and error handling

OpenCode will:

1. Read your project — scan the directory structure and existing files
2. Plan the changes — figure out which files to create or modify
3. Write the code — generate the endpoint, validation, and error handling
4. Show you the diff — display exactly what changed
5. Run tests (if available) — verify the code works

Review the changes. If they look good, accept them. If not, ask OpenCode to revise.

Example: First 5 Tasks for Beginners

Here are five real tasks you can try in your first session:

Task 1: Add a Health Check Endpoint

> Add a GET /health endpoint that returns {"status": "ok"}

Task 2: Write Unit Tests

> Write unit tests for all existing API endpoints using Jest

Task 3: Fix a Bug

> The login function returns 500 when the email is empty. Fix it and add a test.

Task 4: Refactor Code

> Split the utils.js file into separate modules by concern. Update all imports.

Task 5: Add Documentation

> Add JSDoc comments to all exported functions in the src/ directory

OpenCode Commands Reference

Switching AI Models

One of OpenCode's strengths is switching between providers mid-session:

> /model claude-sonnet-4-20250514    # Switch to Claude
> "explain this architecture"
> /model gpt-4o                       # Switch to GPT-4o
> "write unit tests for the auth module"
> /model gemini-2.5-pro               # Switch to Gemini
> "review the full codebase for security issues"

This is useful because different models excel at different tasks. Claude for reasoning, GPT-4o for code generation, Gemini for large context.

Configuring OpenCode for Your Project

OpenCode reads a configuration file called opencode.json in your project root:

{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-your-key",
      "defaultModel": "claude-sonnet-4-20250514"
    },
    "openai": {
      "apiKey": "sk-your-key",
      "defaultModel": "gpt-4o"
    }
  },
  "context": {
    "include": ["src/**", "tests/**"],
    "exclude": ["node_modules", "dist", ".git"]
  }
}

The context section controls which files OpenCode can see. Include your source files and tests. Exclude build artifacts and dependencies.

OpenCode vs Other AI Coding Tools

For a full comparison, see our OpenCode vs Aider and Claude Code vs OpenCode guides.

Using OpenCode with a Multi-Agent Team

OpenCode works great as a standalone coding agent. But if you want to coordinate it with other tools — Claude Code, Cursor, or Aider — in a unified task board, Ivern AI connects them into a coordinated squad.

With Ivern AI you can:

• Assign tasks to OpenCode from a web dashboard
• Coordinate OpenCode with other agents on the same project
• Stream results in real time
• Track costs across all agents in one view

Get started free — 15 tasks included, no credit card required.

Troubleshooting Common Issues

"API key not found"

Set your API key as an environment variable:

export ANTHROPIC_API_KEY=sk-ant-your-key
export OPENAI_API_KEY=sk-your-key

Or add it to opencode.json in your project root.

"Model not available"

Check that your API key has access to the model. Some models require a paid API account. Claude Sonnet 4 and GPT-4o are available on all paid plans.

"OpenCode is slow"

Try these fixes:

1. Use a faster model — Claude Haiku or GPT-4o-mini for quick tasks
2. Limit context — exclude large directories in opencode.json
3. Use a local model — install Ollama for zero-latency inference

"Changes are wrong"

Ask OpenCode to revise:

> The validation is too strict. Allow emails with + signs and hyphens.

OpenCode iterates on its own output. You do not need to start over.

Cost Expectations

With BYOK pricing, you pay only for API usage:

For comparison, a Cursor subscription costs $20/month regardless of usage. See our AI Coding Assistants Pricing comparison for full cost breakdowns.

Frequently Asked Questions

Is OpenCode free?

Yes. OpenCode is open-source (MIT license) and free to install. You provide your own API key and pay the provider directly. Typical cost is $2-8/month.

Does OpenCode work on Windows?

Yes. OpenCode runs in Windows Terminal, PowerShell, and WSL. Install Node.js, then run npm install -g opencode-ai.

Can OpenCode edit multiple files?

Yes. OpenCode reads your full project and can create, modify, and delete multiple files in a single task. It handles import updates and cross-file refactoring.

Does OpenCode work with Python?

Yes. OpenCode works with any programming language. It reads your codebase, understands the project structure, and generates code in whatever language your project uses.

How is OpenCode different from Claude Code?

OpenCode is open-source and supports multiple AI providers (Claude, GPT-4, Gemini). Claude Code is made by Anthropic and only supports Claude models. OpenCode has a richer terminal UI. Claude Code has deeper Claude integration. See our Claude Code vs OpenCode comparison for the full breakdown.

How is OpenCode different from Cursor?

Cursor is an IDE (VS Code fork) with AI built in. OpenCode is a terminal agent that works with any editor. Cursor costs $20/month. OpenCode is free with BYOK. See our Cursor vs OpenCode comparison for details.

Can I use OpenCode with local models?

Yes. Install Ollama, pull a model like ollama pull llama3, then configure OpenCode to use the local endpoint. Cost: $0.

Does OpenCode auto-commit changes?

No. OpenCode makes changes but does not auto-commit to git. You review and commit manually. If you want auto-commits, use Aider instead.

Next Steps

• OpenCode vs Aider: Full Comparison
• OpenCode Full Review and Benchmarks
• Claude Code vs OpenCode
• Cursor vs OpenCode
• Best Free AI Coding Assistants 2026
• AI Coding Assistants Pricing Compared
• Best BYOK AI Platforms
• Build a Multi-Agent AI Team
• AI Agent Cost Calculator
• Try Ivern AI Free — coordinate OpenCode with other agents in one squad