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 (
askmode) - 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 <id>
opencode -s <id>
# Start with specific model
opencode --model <model>
opencode -m <model>
# Start with specific agent
opencode --agent build
opencode --agent planNon-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 webManagement 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 <server>
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 <sessionID>
opencode import <file>
# Upgrade
opencode upgrade
opencode upgrade <version>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):
.agents/skills/<name>/SKILL.md(project, shared with Codex).claude/skills/<name>/SKILL.md(Claude-compatible project)~/.config/opencode/skills/<name>/SKILL.md(global)~/.claude/skills/<name>/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/oropencode.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 referencereferences/tools.md- Tool details and permissionsreferences/agents.md- Agent configuration guide