What is OpenCode? A Complete Guide to the Open Source AI Coding Agent

What is OpenCode?

OpenCode is an open source AI coding agent designed for developers who want AI assistance directly in their terminal. With over 70,000 GitHub stars and 650,000+ monthly active developers, it has quickly become one of the most popular alternatives to commercial tools like Claude Code or Cursor.

Unlike commercial solutions that lock you into specific AI providers, OpenCode gives you complete freedom to choose your preferred LLM—whether that's Claude, OpenAI's GPT models, Google Gemini, or even locally hosted open-source models. Built with Go and using the Bubble Tea framework, it provides a beautiful Terminal User Interface (TUI) that feels native to your workflow.

Key Features

Multi-Model Support

OpenCode isn't tied to a single AI provider. You can configure it to work with:

• Anthropic Claude (Claude 3.5 Sonnet, Opus, etc.)
• OpenAI (GPT-4o, GPT-4 Turbo, etc.)
• Google Gemini (Gemini 2.0 Flash, Pro, etc.)
• Local models via Ollama or similar
• Other providers like Groq, Azure OpenAI, AWS Bedrock

Dual-Mode Workflow

OpenCode features two distinct modes you can toggle with the Tab key:

Plan Mode is perfect for understanding unfamiliar code or reviewing changes before committing. It prevents accidental modifications while still allowing the AI to analyze and explain code.

Privacy First

Your code never passes through OpenCode's servers. The agent communicates directly with your chosen AI provider, and if you use local models, your code stays entirely on your machine. This makes it ideal for enterprise environments or sensitive projects.

File References with @

Use the @ symbol to reference specific files when asking questions:

How does authentication work in @src/auth/index.ts?

This gives the AI precise context and produces more accurate results.

Installation

The easiest way to install OpenCode is using the official install script:

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

Alternative Installation Methods

Using npm:

npm install -g opencode-ai

Using Homebrew (macOS/Linux):

brew install anomalyco/tap/opencode

Using Bun:

bun install -g opencode-ai

Using Scoop (Windows):

scoop install opencode

Using Chocolatey (Windows):

choco install opencode

Configuration

Quick Start with OpenCode Zen

For the easiest setup, OpenCode offers Zen—a curated list of models tested by the OpenCode team:

1. Start OpenCode in your project directory:

   cd /path/to/project
   opencode
   

2. Run the connect command:

   /connect
   

3. Select "opencode" as your provider and visit opencode.ai/auth to get your API key.

Using Third-Party Providers

You can also configure other providers. Create or edit your config file:

• macOS/Linux: ~/.config/opencode/config.json
• Windows: %APPDATA%\opencode\config.json

Example configuration for multiple providers:

{
  "providers": {
    "openai": {
      "apiKey": "your-openai-key",
      "models": ["gpt-4o", "gpt-4-turbo"]
    },
    "anthropic": {
      "apiKey": "your-anthropic-key",
      "models": ["claude-sonnet-4-20250514"]
    }
  },
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514"
}

Getting Started

Initialize Your Project

Before using OpenCode, initialize it for your project:

/init

This command analyzes your codebase and creates an AGENTS.md file that helps OpenCode understand your project structure, coding patterns, and conventions. Commit this file to Git so your team benefits from the shared context.

Essential Commands

Daily Workflow

Asking Questions

Get explanations about your codebase:

How is error handling implemented in @src/utils/errors.ts?

Adding Features

For complex features, start in Plan Mode (press Tab):

1. Plan the feature:

   I need to add a user profile page with avatar upload.
   The page should display the user's name, email, and bio.
   Include an edit mode for updating these fields.
   

2. Review the AI's plan and iterate until you're satisfied.

3. Switch to Build Mode (press Tab again) and execute:

   Looks good! Go ahead and implement this.
   

Making Quick Changes

For straightforward changes, stay in Build Mode:

Refactor the fetchUser function in @src/api/users.ts to use async/await instead of promises.

Undo and Redo

Made a mistake? Simply run:

/undo

You can undo multiple changes in sequence. Made a mistake undoing? Use /redo to restore.

Advanced Features

Custom Commands

Create reusable prompts by saving them as Markdown files in ~/.config/opencode/commands/:

<!-- ~/.config/opencode/commands/refactor.md -->

Refactor this code to:

1. Use TypeScript strict types
2. Add comprehensive error handling
3. Follow the project's naming conventions
4. Add JSDoc comments

Then use it with: /refactor

GitHub Integration

OpenCode integrates with GitHub workflows. Trigger it in PR or Issue comments using /opencode or /oc:

• Automatically analyze issues
• Generate fixes on new branches
• Submit PRs automatically

LSP Support

OpenCode supports the Language Server Protocol for:

• Intelligent code completions
• Real-time error diagnostics
• Automatic file change monitoring

MCP Protocol

Support for the Model Context Protocol allows you to extend OpenCode's capabilities by adding custom MCP servers.

Tips for Best Results

1. Use Plan Mode for exploration—When diving into unfamiliar code, switch to Plan Mode to prevent accidental changes.

2. Be specific with file references—Use @filename to give the AI exact context.

3. Break down complex tasks—Split large features into smaller, verifiable steps.

4. Iterate on plans—Don't accept the first plan blindly. Ask for clarification or modifications.

5. Review before committing—Always review AI-generated changes before merging to production.

Summary

OpenCode brings the power of AI coding assistants to your terminal while keeping you in control. Its open-source nature means:

• No vendor lock-in—Use any AI provider you prefer
• Privacy by default—Your code stays between you and your chosen provider
• Highly customizable—Themes, keybindings, and custom commands
• Free forever—MIT licensed and community-driven

Whether you're refactoring legacy code, exploring a new codebase, or building features from scratch, OpenCode provides an efficient, terminal-native workflow that many developers find more productive than GUI-based alternatives.

Ready to try it? Install with curl -fsSL https://opencode.ai/install | bash and run opencode in your next project.