OpenCode: Complete Guide to Open Source Coding Agent

OpenCode is an open-source AI coding agent that works everywhere: desktop app (macOS/Windows/Linux), terminal (TUI), mobile app (iOS/Android), and via SDK in your scripts/CI. Built by Anomaly team, 227k+ stars on GitHub.

1. Installation & Quick Start

# Easiest way (all platforms)
curl -fsSL https://opencode.ai/v2/install | bash

# Or via package managers
npm install -g @opencode/cli          # Node.js
bun install -g --trust @opencode/cli  # Bun
brew install anomalyco/tap/opencode-v2 # macOS (Homebrew)
paru -S opencode-beta                 # Arch Linux

After install:

opencode              # Launch TUI in terminal
opencode serve        # Start API server for SDK/desktop
opencode auth login   # Auth (optional, for paid models)

2. Core Concepts

Any Model — 200+ Providers

OpenCode uses Models.dev for 200+ LLMs: OpenAI, Anthropic, Google, OpenRouter, Ollama, LM Studio, vLLM, local models. Free models available out of the box.

Any Device — 4 Interfaces

  • Desktop App — native app with tabs, sessions, diffs, built-in browser, extensions
  • Terminal (TUI) — fast interface in any shell, editor, or remote server
  • Mobile — iOS (TestFlight) / Android (Play Store) — manage sessions from phone
  • SDK — drive OpenCode from your scripts, CI, tools (docs)

Multi-Session

Run multiple agents in parallel on the same project — each in its own session with independent context.

3. Advanced Features

Plugins

Hook into OpenCode events, extend logic. Written in TypeScript/JS.

// .opencode/plugins/my-plugin.ts
export default {
  name: "my-plugin",
  hooks: {
    "session:start": async (ctx) => {
      console.log("Session started:", ctx.session.id);
    },
    "tool:call": async (ctx, tool, args) => {
      if (tool === "write") {
        await ctx.runCommand("prettier --write", args.path);
      }
    }
  }
};

MCP Servers

Connect external tools via Model Context Protocol:

# .opencode/mcp.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "$DATABASE_URL"]
    }
  }
}

Custom Agents

Create specialized agents with own prompts, models, tools:

# .opencode/agents/backend-expert.md
---
name: backend-expert
description: "Use for backend development: APIs, databases, architecture."
model: "anthropic/claude-3.5-sonnet"
tools: [read, write, edit, bash, grep, mcp:postgres]
---

You are a backend expert. Focus on:
- Clean architecture, SOLID principles
- Database design, migrations
- API security, rate limiting
- Performance optimization
- Observability

Agent Skills (SKILL.md)

Teach agents reusable workflows:

# .opencode/skills/deploy.md
---
name: deploy
description: "Use when deploying to production. Runs full pipeline."
tools: [bash, read, write, mcp:github]
---

Deploy procedure:
1. Run tests: npm run test
2. Build: npm run build
3. Check bundle size
4. Create GitHub release
5. Deploy to Vercel/AWS
6. Verify health endpoint
7. Notify team

Custom Commands (Slash Commands)

Turn repetitive tasks into reusable commands:

# .opencode/commands/refactor.md
---
name: refactor
description: "Refactor code with safety checks"
args: ["target", "goal"]
---
Refactor $ARG_TARGET to $ARG_GOAL.
Steps:
1. Read file and understand context
2. Write tests if missing
3. Refactor incrementally
4. Run tests after each step
5. Update documentation

Usage: /refactor src/api/users.ts "extract service layer"

Permissions — Action Control

Configure which actions run automatically vs require approval:

# .opencode/permissions.json
{
  "allow": ["read", "grep", "glob", "list"],
  "ask": ["write", "edit", "bash"],
  "deny": ["bash(rm -rf*)", "bash(sudo*)"]
}

Undo / Redo

/undo rolls back recent file changes and conversation. /redo restores.

4. Configuration

Main config: .opencode.json in project root or ~/.config/opencode/config.json globally.

{
  "model": "anthropic/claude-3.5-sonnet",
  "theme": "dark",
  "permissions": {
    "allow": ["read", "grep"],
    "ask": ["write", "bash"]
  },
  "mcpServers": { ... }
}

5. Free Models & OpenCode Go

  • Free models — built-in free models via Models.dev, no account needed
  • OpenCode Go — $10/mo for curated models without limits
  • BYOK — Bring Your Own Key: connect your subscriptions (ChatGPT Plus, GitHub Copilot, Anthropic, OpenRouter)

6. Comparison with Competitors

FeatureOpenCodeClaude CodeCodex
Open Source✅ MIT❌ Proprietary✅ Apache-2.0
Desktop App✅ Native❌ Terminal only❌ Terminal only
Mobile App✅ iOS/Android❌❌
Multi-Session✅❌❌
Plugins✅ TS/JS❌❌
Custom Agents✅✅ Subagents❌
Skills✅ SKILL.md❌❌
MCP✅✅❌
Undo/Redo✅❌❌
200+ Models✅Anthropic onlyOpenAI only
Free Tier✅ Built-inSubscription onlyAPI key required

7. Useful Links

First Run Checklist

  1. curl -fsSL https://opencode.ai/v2/install | bash
  2. opencode — launch TUI
  3. Pick model (free or BYOK)
  4. Enable MCP servers for your tools
  5. Create 1-2 custom agents for your tasks
  6. Configure permissions for your trust level
  7. Try multi-session: multiple tabs over one project