OpenCode AI - AI Code Editor

---

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

❌ **Don't use for:**

---

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

/agents - Agent (Mode) Control

/agents

Available agents:

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

/models - Model Selection

/models

Agent Workflow

#### Plan Agent Behavior

#### Build Agent Behavior

#### 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**:

Other Useful Commands

---

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 <id>`

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:

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:

opencode run --variant high "Solve this complex algorithm problem"
opencode run --variant max "Architect a distributed system"
opencode run --variant minimal "Quick code review"

---

JSON Mode (For Automation)

Use `--format json` for machine-readable output:

opencode run --format json "Refactor this code" | jq .

Useful for:

---

Web Interface

For a GUI experience:

# Start server + open browser
opencode web

# Custom port
opencode web --port 8080

# Custom hostname
opencode web --hostname 0.0.0.0

---

Troubleshooting

"sysctl not found" Error

**Problem**: OpenCode can't find `sysctl` command

**Solution**:

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

Add to `~/.zshrc` to make permanent.

"Failed to change directory" Error

**Problem**: OpenCode treats arguments as directory paths

**Solution**: Use flags like `--version`, `--help`, or `run` explicitly:

# Wrong
opencode version

# Right
opencode --version

OpenCode hangs or freezes

**Problem**: Interactive TUI waiting for input

**Solution**: Press `Ctrl+C` to exit, or use `run` mode for non-interactive tasks.

Permission issues

**Problem**: Can't write to files

**Solution**: Ensure file/directory permissions allow your user to write:

chmod +w ./path/to/file

---

Integration with OpenClaw

Use via exec tool

# For simple tasks
bash command:"opencode run 'Add error handling'"

# For longer tasks (background)
bash background:true command:"opencode run 'Refactor entire codebase'"

Check current sessions

bash command:"opencode session list"

View stats

bash command:"opencode stats"

---

Tips & Best Practices

1. **Be specific**: Clear prompts produce better results

2. **Use files**: Attach relevant files with `-f` for context

3. **Iterate**: Use `--continue` to build on previous work

4. **Fork experiments**: Use `--fork` to try variations safely

5. **Choose models wisely**: Different models excel at different tasks

6. **Monitor costs**: Use `opencode stats` to track token usage

7. **Leverage sessions**: Sessions maintain context across interactions

---

Comparison to Other Tools

| Feature | OpenCode | Cursor | Windsurf | Claude Code |

|---------|----------|--------|----------|-------------|

| Interface | CLI/TUI | GUI | GUI | CLI |

| Terminal-native | ✅ | ❌ | ❌ | ✅ |

| Session management | ✅ | ✅ | ✅ | ✅ |

| GitHub PR integration | ✅ | ✅ | ✅ | ✅ |

| Model support | Multi | Multi | Multi | Anthropic |

| MCP support | ✅ | ❌ | ❌ | ❌ |

**Choose OpenCode when**:

---

Documentation & Resources

---

*Last updated: 2026-02-25*