--- 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"] } }, } ---

OpenCode AI - AI Code Editor

OpenCode is an AI-native code editor that runs in your terminal. Think of it as Cursor or Windsurf, but as a CLI/TUI tool.

Version: 1.2.10 (Homebrew) Platform: macOS Darwin x64

Prerequisites

CRITICAL: OpenCode requires sysctl to detect system architecture. Ensure /usr/sbin is in your PATH:

export PATH="/usr/sbin:/usr/bin:/sbin:/bin:$PATH"

If missing, OpenCode will fail with:

Executable not found in $PATH: "sysctl"

Add this to ~/.zshrc permanently:

echo 'export PATH="/usr/sbin:/usr/bin:/sbin:/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

---

When to Use OpenCode

✅ Use for:

• Complex refactoring across multiple files
• AI-assisted feature implementation
• GitHub PR review and automated fixes
• Exploring and understanding unfamiliar codebases
• Running multi-step coding tasks with context
• Session-based coding (continue previous work)

❌ Don't use for:

• Simple one-line edits (use edit tool)
• Reading file contents (use read tool)
• Non-coding tasks

---

Core Operations (TUI Slash Commands)

When running OpenCode in TUI mode (opencode), you can use these slash commands to control the AI workflow:

/sessions - Session Management

/sessions

• Opens session selector
• Choose to continue an existing session
• Create a new session (with user approval)
• Recommended: Select existing session for current project

/agents - Agent (Mode) Control

/agents

Available agents:

• plan - Planning mode (analyze and design)
• build - Build mode (implement and code)
• explore - Exploration mode (understand codebase)
• general - General assistance

Best Practice: Always select plan first, then switch to build after approval.

/models - Model Selection

/models

• Opens model selector
• Filter by provider (OpenAI, Anthropic, Google, Z.AI, etc.)
• Select preferred model for the task
• If authentication required, follow the login link provided

Agent Workflow

Plan Agent Behavior

• Ask OpenCode to analyze the task
• Request a clear step-by-step plan
• Allow OpenCode to ask clarification questions
• Review the plan carefully
• If plan is incomplete, ask for revision
• Do not allow code generation in Plan mode

Build Agent Behavior

• Switch to Build using /agents
• Ask OpenCode to implement the approved plan
• If OpenCode asks questions, switch back to Plan
• Answer and confirm the plan, then switch back to Build

Plan → Build Loop

1. Select plan agent with /agents
2. Describe the task
3. Review and approve the plan
4. Switch to build agent with /agents
5. Implement the plan
6. Repeat until satisfied

Key Rules:

• Never skip Plan
• Never answer questions in Build mode (switch to Plan first)
• Always show slash commands explicitly in output

Other Useful Commands

• /title - Change session title
• /summary - Generate session summary
• /compaction - Compact conversation history

---

Core Commands

1. Quick Tasks (One-Shot)

# Run a single AI command on a project
opencode run "Add input validation to the login form"

# With specific directory
opencode run --dir ~/path/to/project "Refactor this code to use async/await"

# With specific model
opencode run -m openai/gpt-4o "Optimize the database queries"

# Attach files for context
opencode run -f src/auth.js -f src/database.js "Fix the authentication bug"

# Continue last session
opencode run --continue

# Continue specific session
opencode run --session abc123 --fork

2. Interactive TUI Mode

# Start TUI in current directory
opencode

# Start TUI in specific project
opencode ~/path/to/project

# Start with specific model
opencode -m anthropic/claude-sonnet-4

3. Authentication

# List configured providers
opencode auth list

# Login to a provider (e.g., OpenCode, OpenAI, Anthropic)
opencode auth login [url]

# Logout
opencode auth logout

4. Model Management

# List all available models
opencode models

# List models for specific provider
opencode models openai

# List with cost metadata
opencode models --verbose

# Refresh model cache
opencode models --refresh

5. Session Management

# List all sessions
opencode session list

# Delete a session
opencode session delete <sessionID>

# Export session data
opencode export [sessionID]

# Import session from file
opencode import <file>

6. GitHub Integration

# Fetch and checkout a PR, then run OpenCode
opencode pr 123

# Manage GitHub agent
opencode github --help

7. MCP Servers (Model Context Protocol)

# List MCP servers
opencode mcp list

# Add an MCP server
opencode mcp add

# Authenticate with OAuth MCP server
opencode mcp auth [name]

# Debug OAuth connection
opencode mcp debug <name>

8. Agent Management

# List all agents
opencode agent list

# Create a new agent
opencode agent create

9. Server Mode

# Start headless server
opencode serve

# Start server and open web interface
opencode web

# Start ACP (Agent Client Protocol) server
opencode acp

10. Statistics

# Show token usage and costs
opencode stats

---

Key Options (Global)

| Option | Description | |--------|-------------| | -m, --model | Model to use (format: provider/model) | | -c, --continue | Continue last session | | -s, --session | Continue specific session | | --fork | Fork session when continuing | | --agent | Use specific agent | | --dir | Directory to run in | | --format | Output format: default or json | | --thinking | Show thinking blocks | | --variant | Model reasoning effort (high, max, minimal) |

---

Common Patterns

Pattern 1: Refactor Code

opencode run "Refactor this function to be more readable and add error handling"

Pattern 2: Add Features

opencode run "Add a new API endpoint for user registration with email verification"

Pattern 3: Fix Bugs

opencode run -f error.log -f src/auth.js "Fix the authentication bug described in the error log"

Pattern 4: Review Code

opencode run "Review this code for security vulnerabilities and suggest improvements"

Pattern 5: GitHub PR Workflow

# Auto-fix a PR
opencode pr 123

Pattern 6: Continue Previous Work

# Continue last session
opencode run --continue

# Fork and continue (keeps original intact)
opencode run --continue --fork

---

Session-Based Work

OpenCode maintains sessions that preserve context across runs:

# Start a new session
opencode run "Implement user authentication"

# Continue it later
opencode run --continue

# Or continue a specific session
opencode run --session session-abc123

Session Lifecycle

1. Create: Run opencode run "prompt" or opencode
2. Continue: Use --continue or --session
3. Fork: Use --fork to branch from a session
4. Export: Save session data as JSON
5. Delete: Remove old sessions

---

Model Selection

Format

provider/model

Examples:

• openai/gpt-4o
• anthropic/claude-sonnet-4
• opencode/gpt-4o
• google/gemini-2.5-pro

List Available Models

# All models
opencode models

# Provider-specific
opencode models openai
opencode models anthropic

Model Variants (Reasoning Effort)

Some models support reasoning effort levels:

...