OpenCode Expert

Comprehensive guide for OpenCode - the open-source AI coding agent.

Quick Reference Task Command/Action Start TUI opencode Continue session opencode -c or opencode --continue Run non-interactive opencode run "message" Start headless server opencode serve Web interface opencode web Switch agent Tab key File search @ then type filename Undo changes /undo Redo changes /redo Share conversation /share Initialize project /init Configure API keys /connect Agents

OpenCode has two primary agents, switchable with Tab:

Build Agent (Default) Full access to all tools Can edit files, run commands, make changes Use for active development work Plan Agent Read-only mode for analysis and exploration File edits and bash commands require approval (ask mode) Use for reviewing implementation strategy before changes Subagents

Invoke subagents with @ mention:

@general - Complex research and multi-step tasks with full tool access @explore - Fast read-only codebase searches and code questions Keyboard Shortcuts Key Action Tab Switch between Build and Plan agents @ Fuzzy file search Ctrl+C Cancel current operation Slash Commands Command Description /connect Configure LLM provider API keys /init Initialize project and create AGENTS.md /undo Revert recent changes (stackable) /redo Restore undone changes /share Create shareable conversation link CLI Commands Interactive Mode

Start TUI in current directory

opencode

Start in specific project

opencode /path/to/project

Continue previous session

opencode --continue opencode -c

Use specific session

opencode --session opencode -s

Start with specific model

opencode --model opencode -m

Start with specific agent

opencode --agent build opencode --agent plan

Non-Interactive Mode

Run single prompt

opencode run "Fix the bug in auth.py"

Run with file attachment

opencode run "Review this" --file README.md opencode run "Review this" -f README.md

Run and share result

opencode run "Explain this code" --share

Run specific command

opencode run --command "npm test"

Server Mode

Start headless API server

opencode serve

With custom port

opencode serve --port 3000

With mDNS discovery

opencode serve --mdns

Web interface

opencode web

Management Commands

Authentication

opencode auth login opencode auth list opencode auth logout

Models

opencode models # List available models opencode models --refresh # Refresh model cache

Agents

opencode agent create # Create custom agent opencode agent list # List agents

MCP servers

opencode mcp add opencode mcp list opencode mcp auth opencode mcp debug

Sessions

opencode session list opencode session list -n 10 # Last 10 sessions

Statistics

opencode stats opencode stats --days 7 opencode stats --tools opencode stats --models

Export/Import

opencode export opencode import

Upgrade

opencode upgrade opencode upgrade

Built-in Tools

OpenCode provides these tools to agents:

Tool Description read Read file contents with optional line ranges write Create new files or overwrite existing edit Modify files using exact string replacements patch Apply patch files grep Search file contents with regex glob Find files by pattern (*/.js) list List files and directories bash Execute shell commands lsp Language Server Protocol integration (experimental) todowrite Create/update task lists todoread Read current todo state skill Load skill files into conversation webfetch Fetch and read web pages question Ask user clarifying questions Skills File Locations

Skills are discovered from (in order):

.opencode/skills//SKILL.md (project) ~/.config/opencode/skills//SKILL.md (global) .claude/skills//SKILL.md (Claude-compatible project) ~/.claude/skills//SKILL.md (Claude-compatible global) Skill Format

name: my-skill description: Description of what this skill does and when to use it.

Skill Content

Instructions and documentation here...

Name Rules Lowercase alphanumeric with single hyphens Cannot start/end with hyphens No consecutive hyphens (--) Must match directory name Configuration Config Locations Project: .opencode/ or opencode.json Global: ~/.config/opencode/ Environment Variables Variable Description OPENCODE_CONFIG Custom config path OPENCODE_PERMISSION Permission mode OPENCODE_SERVER_PASSWORD Server auth password OPENCODE_DISABLE_AUTOUPDATE Disable auto-updates OPENCODE_EXPERIMENTAL Enable experimental features OPENCODE_ENABLE_EXA Enable Exa search Custom Agents

Create agents via opencode agent create or define in:

opencode.json ~/.config/opencode/agents/ .opencode/agents/

Agent config options: description, temperature, model, tool permissions, system prompts.

Best Practices Use Plan Mode First

Switch to Plan agent (Tab) to review implementation strategy before making changes.

File References

Use @filename to fuzzy search and reference files in prompts.

Undo Stack

Use /undo liberally - changes are stackable and reversible with /redo.

Session Management

Use --continue or -c to resume previous sessions and maintain context.

References

For detailed documentation, see:

references/cli.md - Complete CLI reference references/tools.md - Tool details and permissions references/agents.md - Agent configuration guide