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

Action	How
Start OpenCode	INLINECODE0
Send message

process.write(sessionId, data: "<json-rpc>\n") | | Read response | process.poll(sessionId) - repeat every 2 seconds | | Stop OpenCode | process.kill(sessionId) | | List sessions | bash(command: "opencode session list", workdir: "...") | | Resume session | List sessions → ask user → session/load | | Check version | bash(command: "opencode --version") |

Starting OpenCode

CODEBLOCK0

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:

CODEBLOCK1

Poll for response. Expect result.protocolVersion: 1.

Step 2: Create Session

CODEBLOCK2

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

Step 3: Send Prompts

CODEBLOCK3

Poll every 2 seconds. You'll receive:

• - session/update notifications (streaming content)
• Final response with INLINECODE13

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)

CODEBLOCK4

No response expected - this is a notification.

State to Track

Per OpenCode instance, track:

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

Polling Strategy

• - Poll every 2 seconds
• Continue until you receive a response with INLINECODE20
• Max wait: 5 minutes (150 polls)
• If no response, consider the operation timed out

Common Stop Reasons

stopReason	Meaning
INLINECODE21	Agent finished responding
INLINECODE22

You cancelled the prompt | | max_tokens | Token limit reached |

Error Handling

Issue	Solution
Empty poll response	Keep polling - agent is thinking
Parse error

Skip malformed line, continue | | Process exited | Restart OpenCode | | No response after 5min | Kill process, start fresh |

Example: Complete Interaction

CODEBLOCK5

---

Resume Session

Resume a previous OpenCode session by letting the user choose from available sessions.

Step 1: List Available Sessions

CODEBLOCK6

Example output:
CODEBLOCK7

Step 2: Ask User to Choose

Present the list to the user and ask which session to resume:

CODEBLOCK8

Step 3: Load Selected Session

Once user responds (e.g., "1", "the first one", or "ses_451cd8ae..."):

1. 1. Start OpenCode ACP:

CODEBLOCK9

1. 2. Initialize:

CODEBLOCK10

1. 3. Load the session:

CODEBLOCK11

Note: session/load requires cwd and mcpServers parameters.

On load, OpenCode streams the full conversation history back to you.

Resume Workflow Summary

CODEBLOCK12

Important Notes

• - History replay: On load, all previous messages stream back
• Memory preserved: Agent remembers the full conversation
• Process independent: Sessions survive OpenCode restarts

---

Updating OpenCode

OpenCode auto-updates when restarted. Use this workflow to check and trigger updates.

Step 1: Check Current Version

CODEBLOCK13

Returns something like: INLINECODE27

Extract the version number (e.g., 1.1.13).

Step 2: Check Latest Version

CODEBLOCK14

The redirect URL contains the latest version tag:

• - Redirects to: INLINECODE29
• Extract version from the URL path (e.g., 1.2.0)

Step 3: Compare and Update

If latest version > current version:

1. 1. Stop all running OpenCode processes:

CODEBLOCK15

1. 2. Restart instances (OpenCode auto-downloads new binary on start):

CODEBLOCK16

1. 3. Re-initialize each instance (initialize + session/load for existing sessions)

Step 4: Verify Update

CODEBLOCK17

If version still doesn't match latest:

• - Inform user: "OpenCode auto-update may have failed. Current: X.X.X, Latest: Y.Y.Y"
• Suggest manual update: INLINECODE31

Update Workflow Summary

CODEBLOCK18

Important Notes

• - Sessions persist: opencodeSessionId survives restarts — use session/load to recover
• Auto-update: OpenCode downloads new binary automatically on restart
• No data loss: Conversation history is preserved server-side