The Complete Guide to OpenCode: Best Practices for AI-Assisted Development

Everything you need to know about using OpenCode effectively, from installation to advanced workflows.

---

If you've been following the AI coding tool landscape, you've probably heard of Claude Code and Cursor. But there's a powerful open-source alternative that's quietly accumulated 45,000+ GitHub stars: OpenCode.

I spent a week diving deep into how developers are using OpenCode in production. After analyzing 21 sources—from official documentation to expert case studies—here's the definitive guide to getting the most out of this tool.

What is OpenCode?

OpenCode is an open-source AI coding agent built in Go that runs in your terminal. Unlike proprietary alternatives, it supports 75+ LLM providers—from cloud APIs (OpenAI, Anthropic, Google) to completely local models via Ollama and Docker Model Runner.

The killer feature? Flexibility without sacrifice. As one comparison noted: "If the best agentic coding models change from Anthropic tomorrow, you're not locked in."

Installation

Getting started takes under a minute:

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

# Alternative: Homebrew
brew install opencode

# Alternative: npm
npm install -g opencode-ai

The Single Most Important Best Practice

Every source I analyzed—from official docs to expert tutorials—emphasized the same workflow:

The Plan-Build Pattern

1. Start in Plan mode (read-only analysis)
2. Review the analysis before proceeding
3. Switch to Build mode for implementation
4. Use /undo and /redo to iterate

This mirrors how senior developers work: understand before modifying. Tools that skip planning produce more errors.

# Start OpenCode in your project
cd your-project
opencode

# Press Tab to switch to Plan mode
# Ask: "Analyze this codebase and suggest improvements"
# Review the analysis

# Press Tab again for Build mode
# Ask: "Implement the authentication refactor"

Key quote from the docs: "Best practice involves evaluating changes with the Plan agent first, then applying them via the Build agent."

Setting Up Your Project: AGENTS.md

The second most important practice is creating a proper AGENTS.md file. Think of it as "a README for agents"—it tells AI tools how to work with your specific project.

Run /init to generate one automatically, then customize:

# Project: MyApp

## Overview
E-commerce platform built with Next.js and Prisma.

## Architecture
- `/src/app` - Next.js app router pages
- `/src/components` - React components
- `/src/lib` - Utilities and database client
- `/prisma` - Database schema

## Conventions
- Use TypeScript strict mode
- Prefer server components where possible
- Tests required for all API routes
- Use Tailwind for styling

## Commands
- `npm run dev` - Development server
- `npm run test` - Run tests
- `npm run build` - Production build

## Security
- Never commit .env.local
- All user input must be validated with Zod
- Use parameterized queries only

Why this matters: A well-crafted AGENTS.md transforms generic AI suggestions into project-specific guidance. The investment compounds over every interaction.

Bonus: AGENTS.md is supported by 10+ tools including OpenAI Codex, Google Jules, Aider, and Devin. Your configuration isn't locked to OpenCode.

Essential Commands

Command	Shortcut	Purpose
/init	-	Generate AGENTS.md
/undo	Ctrl+x, u	Revert changes
/redo	Ctrl+x, r	Reapply changes
/sessions	-	Manage conversation sessions
/share	-	Share session with team
/themes	Ctrl+x, t	Change appearance
Tab	Tab	Switch Plan/Build mode
@	@	Fuzzy file search

The Privacy Option: Local Models

One of OpenCode's killer features is running completely local—your code never leaves your machine.

Option 1: Ollama

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a coding model
ollama pull qwen3-coder

# Configure OpenCode
# In opencode.json:
{
  "model": "ollama/qwen3-coder"
}

Option 2: Docker Model Runner

# Enable TCP in Docker Desktop (port 12434)
# Increase context window (default 4096 is too small)
docker model configure --context-window 32768

Benefits of local models:

• Complete privacy—code never leaves your infrastructure
• Zero per-token costs after initial download
• No rate limits
• Works offline
• Compliance-friendly for regulated industries

Advanced: Custom Commands

Create reusable prompts in .opencode/command/:

<!-- .opencode/command/review.md -->
---
agent: plan
---
Review this code for:
1. Security vulnerabilities
2. Performance issues
3. Code style violations
4. Missing tests

Provide specific, actionable feedback.

Now just type /review to run it.

Advanced: MCP Server Integration

MCP (Model Context Protocol) servers extend OpenCode with external tools:

// opencode.json
{
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "github-mcp-server"],
      "environment": {
        "GITHUB_TOKEN": "{env:GITHUB_TOKEN}"
      }
    }
  }
}

Warning: Some MCP servers (like GitHub) add 20k+ tokens to context. Enable them per-agent rather than globally.

The tmux Workflow

Power users combine OpenCode with terminal multiplexers for maximum efficiency:

┌─────────────────────────────────────────────────┐
│ Pane 1: Neovim (code editing)                   │
├─────────────────────────────────────────────────┤
│ Pane 2: Dev server      │ Pane 3: OpenCode      │
│ (npm run dev)           │ (AI assistant)        │
└─────────────────────────────────────────────────┘

This lightweight setup rivals full IDEs without the resource overhead.

OpenCode vs. Claude Code vs. Cursor

Aspect	OpenCode	Claude Code	Cursor
Price	Free	$100-200/mo	$20/mo
Open Source	Yes	No	No
Model Choice	75+ providers	Anthropic only	Multiple
Interface	Terminal	Terminal	IDE
Local Models	Yes	No	Limited

The insight from my research: "Cursor makes you faster at what you already know. Claude Code does things for you." OpenCode gives you the autonomy of Claude Code with the flexibility of choice.

Many developers use Cursor for quick edits and OpenCode/Claude Code for complex autonomous tasks.

Common Mistakes to Avoid

1. Vague prompts: "Make it better" vs. "Refactor handleSubmit to use async/await with try-catch error handling"

2. Skipping Plan mode: Always analyze before modifying, even for "simple" changes

3. Neglecting AGENTS.md: The 5 minutes you spend here saves hours later

4. Ignoring sessions: Use /sessions to maintain context across breaks

5. Global MCP servers: Enable them per-agent to avoid context bloat

The Productivity Reality Check

The OpenCode creator offers a sobering insight: "The feeling of productivity is not the same as actual productivity."

Yet case studies show dramatic gains—"tasks that would have taken days now take hours."

Resolution: AI tools amplify existing capabilities. Well-organized developers and codebases benefit enormously. Measure outcomes, not activity.

Getting Started Today

1. Install OpenCode: curl -fsSL https://opencode.ai/install | bash
2. Navigate to your project: cd your-project
3. Launch: opencode
4. Initialize: /init
5. Review and customize your AGENTS.md
6. Start with Plan mode (Tab) for your first task

The tools are mature. The workflows are proven. The only variable is whether you adopt them.

---

Resources

Official:

• OpenCode Documentation
• OpenCode GitHub
• AGENTS.md Specification

Tutorials:

• freeCodeCamp Guide
• Docker Private AI Setup

Comparisons:

• OpenCode vs Claude Code
• OpenCode vs Claude Code vs Cursor

---

What workflows have you developed with OpenCode? Share in the comments.