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 <id>
opencode -s <id>

# Start with specific model
opencode --model <model>
opencode -m <model>

# 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 <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):

1. .agents/skills/<name>/SKILL.md (project, shared with Codex)
2. .claude/skills/<name>/SKILL.md (Claude-compatible project)
3. ~/.config/opencode/skills/<name>/SKILL.md (global)
4. ~/.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/ 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