OpenCode Expert

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

Quick Reference

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

Slash Commands

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:

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

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