- name
- opencode
- description
- OpenCode AI - AI-driven code editor/IDE (CLI/TUI version of Cursor/Windsurf). Use when: (1) AI-assisted coding tasks, (2) Code refactoring with AI, (3) GitHub PR review/fixes, (4) Multi-file edits requiring context, (5) Running AI agents on codebases. NOT for: simple one-line edits (use edit tool), reading files (use read tool).
- metadata
- openclaw
- emoji
- 🤖
- requires
- bins
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 permanenceWhen 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 projectTUI Slash Commands
/sessions— Session selector (continue existing or create new)/agents— Switch agent (see agents below)/models— Model selector/title— Change session title/summary— Generate session summary/compaction— Compact conversation history
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 |
⚠️--agentflag inopencode runalways falls back to default agent. Agent switching only works in TUI via/agentsslash command.
Recommended Workflow: Plan → Build
- Select plan agent (
/agents) - Describe task → review/approve the plan
- Switch to build agent (
/agents) - 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 <file> # 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 <module> # 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 <url> # 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 toolsIntegration with OpenClaw
You are the orchestrator. OpenCode is your worker.
When to Delegate
- Multi-file refactoring
- Complex feature implementation
- PR review and fixes
- Code exploration requiring sustained context
When to Do It Yourself
- Simple one-line edits
- Reading files
- Quick commands
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 --continueMulti-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*