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

• .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/ 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