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:

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:

• CI/CD integration
• Scripting
• Parsing results programmatically

---

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:

• You prefer terminal workflows
• Need CI/CD integration
• Want headless/server mode
• Require MCP protocol support

---

Documentation & Resources

• Version: opencode --version
• Help: opencode --help or opencode --help
• Models: opencode models --verbose
• Sessions: opencode session list

---

Last updated: 2026-02-25