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

bash

# 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

bash

# 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

bash

# 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

bash

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

•.opencode/skills/<name>/SKILL.md (project)
•~/.config/opencode/skills/<name>/SKILL.md (global)
•.claude/skills/<name>/SKILL.md (Claude-compatible project)
•~/.claude/skills/<name>/SKILL.md (Claude-compatible global)

Skill Format

markdown

---
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