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
| Option | Pros | Cons | Best For |
|---|---|---|---|
| Free Models (built-in) | No keys, works instantly, private | Less context, lower quality | Tests, learning, pet projects |
| OpenRouter (1 key = 100+ models) | GPT-4o, Claude, Gemini, Llama, free :free | Needs OpenRouter account | Production, model selection per task |
| Anthropic Direct | Best Claude 3.5 Sonnet | Requires $20/mo subscription | Serious code, refactoring |
| Ollama / LM Studio (local) | Full privacy, free, offline | Needs hardware (16-32GB RAM) | Private projects, offline |
| OpenCode Go ($10/mo) | Curated models, no limits, no keys | Paid | Teams, 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
- Open 2 terminals in same folder
- First:
opencode→ "Write tests for user service" - Second:
opencode→ "Refactor user controller" - 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
- Official Docs — best starting place
- GitHub (227k★) — issues, discussions, examples
- Discord — community, help, examples
- Plugins API — how to write your own
- Skills Docs — procedural memory
First Day Checklist ✅
- [ ]
curl -fsSL https://opencode.ai/v2/install | bash - [ ]
opencode— launch, pick Free Model - [ ] Create
.opencode.jsonwith model and MCP - [ ] Add GitHub + Filesystem MCP
- [ ] Create 1 custom agent (code-reviewer)
- [ ] Configure permissions (allow/ask/deny)
- [ ] Try multi-session (2 terminals)
- [ ] Create 1 slash-command (/refactor)
- [ ] Test /undo
- [ ] Join Discord
