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:

```bash
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)

```bash
# 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

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

#### TUI 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 |

> ⚠️ `--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

```bash
# 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 tools
```

---

## Integration 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

```bash
# 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

```bash
# 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*