OpenCode AI

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).

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