OpenCode ACP Skill

Control OpenCode directly via the Agent Client Protocol (ACP).

Metadata

• For ACP Protocol Docs (for Agents/LLMs): https://agentclientprotocol.com/llms.txt
• GitHub Repo: https://github.com/bjesuiter/opencode-acp-skill
• If you have issues with this skill, please open an issue ticket here: https://github.com/bjesuiter/opencode-acp-skill/issues

Quick Reference

Starting OpenCode

bash(
  command: "opencode acp",
  background: true,
  workdir: "/path/to/your/project"
)

Save the returned sessionId - you'll need it for all subsequent commands.

Protocol Basics

• All messages are JSON-RPC 2.0 format
• Messages are newline-delimited (end each with \n)
• Maintain a message ID counter starting at 0

Step-by-Step Workflow

Step 1: Initialize Connection

Send immediately after starting OpenCode:

{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{"fs":{"readTextFile":true,"writeTextFile":true},"terminal":true},"clientInfo":{"name":"clawdbot","title":"Clawdbot","version":"1.0.0"}}}

Poll for response. Expect result.protocolVersion: 1.

Step 2: Create Session

{"jsonrpc":"2.0","id":1,"method":"session/new","params":{"cwd":"/path/to/project","mcpServers":[]}}

Poll for response. Save result.sessionId (e.g., "sess_abc123").

Step 3: Send Prompts

{"jsonrpc":"2.0","id":2,"method":"session/prompt","params":{"sessionId":"sess_abc123","prompt":[{"type":"text","text":"Your question here"}]}}

Poll every 2 seconds. You'll receive:

• session/update notifications (streaming content)
• Final response with result.stopReason

Step 4: Read Responses

Each poll may return multiple lines. Parse each line as JSON:

• Notifications: method: "session/update" - collect these for the response
• Response: Has id matching your request - stop polling when stopReason appears

Step 5: Cancel (if needed)

{"jsonrpc":"2.0","method":"session/cancel","params":{"sessionId":"sess_abc123"}}

No response expected - this is a notification.

State to Track

Per OpenCode instance, track:

• processSessionId - from bash tool (clawdbot's process ID)
• opencodeSessionId - from session/new response (OpenCode's session ID)
• messageId - increment for each request you send

Polling Strategy