OpenCode: Perfect Start Checklist

OpenCode differs from other agents: it gives you freedom to choose models, tools, control level. But with great power comes responsibility — here's what to know to not waste time on setup.

1. Installation — 30 Seconds

# One-liner for all platforms
curl -fsSL https://opencode.ai/v2/install | bash

# Verify
opencode --version
# OpenCode v0.x.x

Works on macOS, Linux, Windows (WSL2), Docker, CI.

2. Model Selection: Free vs BYOK

OptionProsConsBest For
Free Models (built-in)No keys, works instantly, privateLess context, lower qualityTests, learning, pet projects
OpenRouter (1 key = 100+ models)GPT-4o, Claude, Gemini, Llama, free :freeNeeds OpenRouter accountProduction, model selection per task
Anthropic DirectBest Claude 3.5 SonnetRequires $20/mo subscriptionSerious code, refactoring
Ollama / LM Studio (local)Full privacy, free, offlineNeeds hardware (16-32GB RAM)Private projects, offline
OpenCode Go ($10/mo)Curated models, no limits, no keysPaidTeams, production without BYOK

Tip: Start with Free Models → switch to OpenRouter when quality needed.

3. Config: .opencode.json

Create in project root:

{
  "model": "openrouter/anthropic/claude-3.5-sonnet",
  "theme": "dark",
  "permissions": {
    "allow": ["read", "grep", "glob", "list"],
    "ask": ["write", "edit", "bash"]
  },
  "mcpServers": {
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] }
  }
}

Global config: ~/.config/opencode/config.json — for defaults.

4. MCP — Connect Your Tools in 2 Minutes

Create .opencode/mcp.json:

{
  "mcpServers": {
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] },
    "postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres", "$DATABASE_URL"] },
    "brave-search": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-brave-search", "$BRAVE_API_KEY"] }
  }
}

Restart opencode — agent sees your GitHub, files, DB, web search.

5. Create Your First Custom Agent

File .opencode/agents/code-reviewer.md:

---
name: code-reviewer
description: "Use for code review before commit. Checks bugs, style, security."
model: "anthropic/claude-3.5-sonnet"
tools: [read, grep, glob, bash]
---

You are a senior code reviewer. Focus on:
1. Security (SQLi, XSS, path traversal)
2. Performance (N+1, re-renders)
3. Style consistency
4. Test coverage gaps
5. Error handling

Output format:
- **Critical**: must fix
- **Warning**: should fix
- **Nitpick**: optional

Usage: /agent code-reviewer "Review my changes"

6. Permissions — Configure Trust

Don't give full rights immediately. Start conservative:

{
  "allow": ["read", "grep", "glob", "list"],
  "ask": ["write", "edit", "bash"],
  "deny": ["bash(rm -rf*)", "bash(sudo*)", "write(*.env)", "write(*.key)"]
}

Gradually move from ask to allow as trust builds.

7. First Multi-Session

  1. Open 2 terminals in same folder
  2. First: opencode → "Write tests for user service"
  3. Second: opencode → "Refactor user controller"
  4. Watch them work in parallel on different files

8. Useful Aliases

# ~/.bashrc / ~/.zshrc
alias oc='opencode'
alias ocs='opencode serve'
alias oca='opencode auth login'
alias ocp='opencode -p'

# Quick launch with model
alias oc-claude='opencode -m anthropic/claude-3.5-sonnet'
alias oc-gpt='opencode -m openai/gpt-4o'
alias oc-free='opencode -m free'

9. Common Beginner Mistakes

  • Give all permissions immediately → agent may delete important stuff. Start with ask.
  • Don't configure MCP → agent blind to GitHub, DB, web. Add at least GitHub + Filesystem.
  • Use free models for production code → lower quality. Switch to paid for important work.
  • Don't create .opencode.json in project → settings reset on restart.
  • Don't use /undo → afraid to experiment. Experiment boldly — rollback in one command.

10. Resources for Deep Dive

First Day Checklist ✅

  1. [ ] curl -fsSL https://opencode.ai/v2/install | bash
  2. [ ] opencode — launch, pick Free Model
  3. [ ] Create .opencode.json with model and MCP
  4. [ ] Add GitHub + Filesystem MCP
  5. [ ] Create 1 custom agent (code-reviewer)
  6. [ ] Configure permissions (allow/ask/deny)
  7. [ ] Try multi-session (2 terminals)
  8. [ ] Create 1 slash-command (/refactor)
  9. [ ] Test /undo
  10. [ ] Join Discord