OpenCode AI

OpenCode AI - AI Code Editor

OpenCode is an AI-native code editor that runs in your terminal (CLI/TUI). Think Cursor/Windsurf but in the terminal.

Version: 1.3.9 | Platform: macOS Darwin x64

Prerequisites

OpenCode requires sysctl for architecture detection. Ensure /usr/sbin is in PATH:

export PATH="/usr/sbin:/usr/bin:/sbin:/bin:$PATH"
Add to ~/.zshrc for permanence

When to Use

✅ Use for: Complex refactoring, AI-assisted features, PR review/fixes, codebase exploration, multi-file edits, session-based coding ❌ Don't use for: Simple one-line edits (use edit tool), reading files (use read tool)

Core Commands

Quick Tasks (One-Shot)

# Run a single task
opencode run "Add input validation to the login form"
opencode run --dir ~/project "Refactor to use async/await"
opencode run -m anthropic/claude-sonnet-4 "Optimize queries"
Attach files for context
opencode run -f src/auth.js -f src/db.js "Fix the auth bug"
Continue previous session
opencode run --continue
opencode run --session abc123 --fork
Share session (creates shareable link)
opencode run --share "Implement feature X"
Model variant (reasoning effort)
opencode run --variant high "Solve this complex problem"

Key Options

| Option | Description | |--------|-------------| | -m, --model | Model (provider/model, e.g. anthropic/claude-sonnet-4) | | -c, --continue | Continue last session | | -s, --session | Continue specific session | | --fork | Fork session when continuing | | --share | Share the session | | -f, --file | Attach files to message | | --agent | Use specific agent | | --dir | Directory to run in | | --format | Output format: default or json | | --variant | Reasoning effort: high, max, minimal | | --thinking | Show thinking blocks | | --title | Set session title | | --attach | Attach to running server (e.g. http://localhost:4096) | | --pure | Run without external plugins | | --command | Run a specific command (use message for args) | | -p, --password | Basic auth password for server mode |

Interactive TUI

opencode              # Start in current directory
opencode ~/project    # Start in specific project

#### TUI Slash Commands

#### Available Agents

| Agent | Type | Purpose | |-------|------|---------| | plan | primary | Analyze & design (no code edits) | | build | primary | Implement & code | | explore | subagent | Understand codebase, read-only exploration | | general | subagent | General assistance | | compaction | primary | Compress/summarize session context | | summary | primary | Generate session summaries | | title | primary | Generate session titles | | memory-automation | subagent | Automated memory management | | memory-consolidate | subagent | Consolidate memory entries |

> ⚠️ --agent flag in opencode run always falls back to default agent. Agent switching only works in TUI via /agents slash command.

#### Recommended Workflow: Plan → Build

1. Select plan agent (/agents) 2. Describe task → review/approve the plan 3. Switch to build agent (/agents) 4. Implement → iterate

Other Commands

# Providers & Auth
opencode providers              # Manage AI providers/credentials (alias: auth)
opencode providers login [url] # Login to a provider
Models
opencode models                 # List all models
opencode models --verbose       # With cost info
opencode models --refresh       # Refresh cache
Sessions
opencode session list            # List sessions
opencode export [sessionID]      # Export as JSON
opencode import            # Import session
GitHub
opencode pr 123                  # Checkout PR + run OpenCode
opencode github --help           # GitHub agent options
MCP Servers
opencode mcp list                # List MCP servers
opencode mcp add                 # Add MCP server
opencode mcp auth [name]         # OAuth for MCP server
Agents
opencode agent list              # List agents
opencode agent create            # Create custom agent
Plugins
opencode plugin         # Install plugin (alias: plug)
Server Mode
opencode serve                   # Headless server
opencode web                     # Server + open browser
ACP (Agent Client Protocol)
opencode acp                     # Start ACP server
Attach to Remote
opencode attach             # Attach to running instance
Utilities
opencode stats                   # Token usage & costs
opencode debug                   # Debug/troubleshooting tools
opencode upgrade [target]       # Upgrade opencode
opencode uninstall               # Remove opencode
opencode db                      # Database tools

Integration with OpenClaw

You are the orchestrator. OpenCode is your worker.

When to Delegate

When to Do It Yourself

Pattern: Delegate via exec

# Simple task (foreground, wait for result)
opencode run "Add error handling to auth module"
Complex task (background, check later)
Use exec with background:true
With file context
opencode run -f src/auth.js -f src/db.js "Fix the auth bug"
Continue previous work
opencode run --continue

Multi-Agent Pattern

# Agent 1: Analyze
opencode run --session analyze "Explore codebase structure"
Agent 2: Implement
opencode run --session implement "Implement feature based on analysis"
Agent 3: Test
opencode run --session test "Write tests for the implementation"

Troubleshooting

| Problem | Solution | |---------|----------| | sysctl not found | export PATH="/usr/sbin:/usr/bin:/sbin:/bin:$PATH" | | Failed to change directory | Use --version or run subcommand explicitly | | Freezes/hangs | Ctrl+C to exit; use run mode for non-interactive tasks | | Permission denied | chmod +w ./path/to/file |

*Last updated: 2026-04-16 | OpenCode v1.3.9*

OpenCode requires sysctl for architecture detection. Ensure /usr/sbin is in PATH:

export PATH="/usr/sbin:/usr/bin:/sbin:/bin:$PATH"
Add to ~/.zshrc for permanence

| Problem | Solution | |---------|----------| | sysctl not found | export PATH="/usr/sbin:/usr/bin:/sbin:/bin:$PATH" | | Failed to change directory | Use --version or run subcommand explicitly | | Freezes/hangs | Ctrl+C to exit; use run mode for non-interactive tasks | | Permission denied | chmod +w ./path/to/file |

*Last updated: 2026-04-16 | OpenCode v1.3.9*