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

Security Scan

The skill's files, declared requirements, and runtime instructions are consistent with a CLI/TUI wrapper that delegates work to an external opencode binary; nothing in the bundle asks for unrelated credentials or hidden network endpoints.

Purpose & Capability

The skill is an instruction-only adapter for the opencode CLI/TUI. Declaring the 'opencode' binary as the required executable matches the described purpose (AI-assisted coding, multi-file edits, PR workflows). The tool-level commands and model/auth flows are coherent with an editor that integrates with multiple model providers.

Instruction Scope

SKILL.md and examples instruct the agent/user to run the opencode CLI and to provide files via opencode's -f flags; that implies the opencode binary will access repository files — which is expected for this use case. The docs repeatedly instruct adding /usr/sbin to PATH and show auth/login flows. One minor oddity: INSTALL.md uses a hard-coded developer path (/Users/wl/.openclaw/workspace/skills/opencode) as the copy source, which appears to be a leftover dev path and should be adjusted by an installer.

Install Mechanism

There is no automated install spec in the skill bundle (instruction-only), so nothing will be written/executed by the skill itself. The README/INSTALL recommend installing the external 'opencode' binary via Homebrew and copying the skill into OpenClaw's skills directory with sudo — these are typical manual steps and not intrinsically risky, but they require user action and root privileges.

Credentials

The skill requests no environment variables or credentials in its metadata. SKILL.md documents provider authentication flows (opencode auth login) but does not demand unrelated keys from the user. No excessive or unrelated environment/secret access is requested by the skill bundle itself.

Persistence & Privilege

The skill does not request always:true and will not autonomously persist beyond normal installation. INSTALL.md instructs copying the skill into OpenClaw's system directory (requiring sudo) and optionally setting ownership to root:wheel — that is standard for installing a system-level skill but does grant the skill a persistent presence inside OpenClaw once installed. This is expected for a skill and not disproportionate.

Assessment

This skill is an instruction-only integration that expects you to already install the external 'opencode' CLI (recommended via Homebrew). Before installing: (1) verify the opencode binary comes from a trusted source (Homebrew or the vendor) — the skill itself does not provide the binary; (2) note INSTALL.md uses sudo to copy files into OpenClaw's system directory and even sets root ownership — those steps will require admin rights and create a persistent skill entry in OpenClaw; (3) the INSTALL file references a developer path (/Users/wl/...) which you'll need to replace with your actual source path if copying manually; (4) the skill will cause the opencode binary to read and modify project files when you invoke it (expected for an editor) — do not grant it sensitive repositories unless you trust the binary; (5) there is no evidence of hidden network endpoints or requests for unrelated credentials in the skill bundle, but because the source/homepage are missing, prefer obtaining the opencode binary from an official channel and review the binary's provenance before use.

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

• 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 <command> --help
• Models: opencode models --verbose
• Sessions: opencode session list

---

Last updated: 2026-02-25