Opencode Cli

OpenCode CLI integration skill. Designed for AI agents like OpenClaw to execute coding tasks via OpenCode CLI. Core features: (1) Plan→Build workflow (2) Session management (3) MCP integration (4) Background task monitoring. Use this skill when you need: multi-step coding, Plan→Build workflow, MCP integration, or background task monitoring. NOT for: simple one-line edits (use edit tool directly), quick file reads (use read tool directly).

OpenCode CLI Integration

This skill is designed for AI agents like OpenClaw to execute coding tasks via OpenCode CLI.

OpenCode is an AI-powered code editor CLI. When called via OpenClaw, only CLI mode is used.

---

Security Scope

What this skill does:

• Integrates with OpenCode CLI for coding tasks
• Manages sessions, plans, and builds
• Optionally connects to configured MCP servers (Playwright, Supabase, Context7)

What this skill does NOT do:

• Install or modify system-wide packages
• Access credentials outside configured MCP servers
• Persist beyond user-initiated sessions

Credential access:

• MCP servers (if configured) may use environment variables like SUPABASE_URL, SUPABASE_ANON_KEY, CONTEXT7_API_KEY
• Skills run in project context; avoid committing secrets to version control
• Only use this skill in repositories/environments you trust

---

Core Command

opencode run -m <provider/model> -- "<prompt>"

Example:

opencode run -m <provider/model> -- "Add error handling to the login function"

---

Plan→Build Workflow (Core)

⚠️ Key Rule: Maintain Same Session

Correct approach:

# 1. Start Plan (creates session)
opencode run -m <model> -- 'Analyze task, output plan.'

# 2. Wait for user APPROVE

# 3. Switch to Build (continue same session)
opencode run --continue --agent build -- 'Implement approved plan.'

Wrong approach (context lost):

❌ opencode run --agent plan "..."   # session A
❌ opencode run --agent build "..."  # session B (separate!)

Agent Options

Agent	Purpose
plan	Planning, analysis, design
build	Implementation, coding, modification
explore	Codebase exploration

---

Session Management

opencode run --continue -- '<prompt>'
opencode run --session <id> -- '<prompt>'
opencode run --continue --fork -- '<prompt>'
opencode session list
opencode session delete <id>

---

OpenClaw Integration

Standard Task

opencode run -m <model> -- '<task>'

Background Task

opencode run -m <model> -- '<task>'
process action:poll sessionId:<id> timeout:30000
process action:log sessionId:<id>
process action:kill sessionId:<id>

Monitoring Discipline

⚠️ Mandatory: After starting, must actively monitor. Do not wait for system event.

Start → Get sessionId
  ↓
Every 30-60s: poll + log
  ↓
Progress → Report
Error → Report immediately
Complete → Report result (do not wait for event)

Violation criteria:

• Start without monitoring → Abandoning responsibility
• User asks "is it done?" before checking → Failure

---

MCP Integration

OpenCode supports MCP integration to extend capabilities. Must run in project root directory.

Common tools: Playwright (UI automation), Supabase (database)

Scenario guide:

Scenario	Reference
Need UI automation testing (Playwright)	references/mcp-config-guide.md
Need database operations (Supabase)	references/mcp-config-guide.md
MCP not loading, troubleshoot config	references/mcp-config-guide.md

---

Built-in Tools

OpenCode Agent built-in tools: read/write/edit, bash, grep/glob, todowrite, skill, webfetch

Scenario guide:

Scenario	Reference
Unsure if Agent can perform an operation	references/built-in-tools-guide.md
Plan Agent reports insufficient permissions	references/built-in-tools-guide.md (see tool permissions table)

---

Practical Tips

• File reference: Use @filename to quickly reference files
• Undo changes: /undo to undo, /redo to restore

Scenario guide:

Scenario	Reference
Want to reference file instead of typing path	references/tips-guide.md (file reference)
Made mistake and want to rollback	references/tips-guide.md (undo/redo)
Want to learn TUI shortcuts	references/tips-guide.md (shortcuts)

---

Skills Configuration

Scenario guide:

Scenario	Reference
Want to add custom skill	references/skills-config-guide.md
Unsure where to place skill files	references/skills-config-guide.md

---

Common Patterns

Note: Examples use openclaw system event for optional task notification. This is an OpenClaw platform command. Omit if running outside OpenClaw.

Planning Task

opencode run -m <model> -- 'Analyze task, output plan.'

For detailed plan format, see project workflow documentation.

Implementation Task

opencode run -m <model> -- 'Execute approved plan.'

Verify with: npm run build && npm test

Database Operations

cd /path/to/project
opencode run -m <model> -- 'Use Supabase MCP for database operations.'

See: references/mcp-config-guide.md for MCP setup.

UI Testing

opencode run -m <model> -- 'Use Playwright MCP for UI testing.'

See: references/mcp-config-guide.md for MCP setup.

---

Troubleshooting

sysctl not found

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

MCP not loading

Ensure running in project root:

cd /path/to/project && opencode run ...

See: references/mcp-config-guide.md

Session context lost

Use --continue instead of separate starts:

✅ opencode run --continue --agent build "..."
❌ opencode run --agent build "..."

---

Quick Reference

Common Commands

Task	Command
Plan task	opencode run -m <model> -- 'Analyze...'
Build (continue session)	opencode run --continue --agent build -- 'Implement...'
Continue last session	opencode run --continue
Specific session	opencode run --session <id>
Fork session	opencode run --continue --fork
List sessions	opencode session list
Delete session	opencode session delete <id>
View models	opencode models

OpenClaw Integration

Task	Command
Background task	pty:true background:true command:"opencode run..."
Monitor progress	process action:poll sessionId:<id>
View logs	process action:log sessionId:<id>
Terminate task	process action:kill sessionId:<id>

Configuration Guide Index

Scenario	Reference
UI automation / Database operations	references/mcp-config-guide.md
Agent tool capabilities / Permissions	references/built-in-tools-guide.md
Shortcuts / File reference / Undo	references/tips-guide.md
Add custom skill	references/skills-config-guide.md

---

CLI Integration v2.6 - 2026-04-05