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. .opencode/skills/<name>/SKILL.md (project)
2. ~/.config/opencode/skills/<name>/SKILL.md (global)
3. .claude/skills/<name>/SKILL.md (Claude-compatible project)
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