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 | bash(command: "opencode acp --cwd /path/to/project", background: true) |

| Send message | process.write(sessionId, data: "\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

bash(
  command: "opencode acp --cwd /path/to/your/project",
  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

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

Common Stop Reasons

| stopReason | Meaning |

|------------|---------|

| end_turn | Agent finished responding |

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

1. bash(command: "opencode acp --cwd /home/user/myproject", background: true, workdir: "/home/user/myproject")
   -> processSessionId: "bg_42"

2. process.write(sessionId: "bg_42", data: '{"jsonrpc":"2.0","id":0,"method":"initialize",...}\n')
   process.poll(sessionId: "bg_42") -> initialize response

3. process.write(sessionId: "bg_42", data: '{"jsonrpc":"2.0","id":1,"method":"session/new","params":{"cwd":"/home/user/myproject","mcpServers":[]}}\n')
   process.poll(sessionId: "bg_42") -> opencodeSessionId: "sess_xyz789"

4. process.write(sessionId: "bg_42", data: '{"jsonrpc":"2.0","id":2,"method":"session/prompt","params":{"sessionId":"sess_xyz789","prompt":[{"type":"text","text":"List all TypeScript files"}]}}\n')
   
5. process.poll(sessionId: "bg_42") every 2 sec until stopReason
   -> Collect all session/update content
   -> Final response: stopReason: "end_turn"

6. When done: process.kill(sessionId: "bg_42")

---

Resume Session

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

Step 1: List Available Sessions

bash(command: "opencode session list", workdir: "/path/to/project")

Example output:

ID                                  Updated              Messages
ses_451cd8ae0ffegNQsh59nuM3VVy      2026-01-11 15:30     12
ses_451a89e63ffea2TQIpnDGtJBkS      2026-01-10 09:15     5
ses_4518e90d0ffeJIpOFI3t3Jd23Q      2026-01-09 14:22     8

Step 2: Ask User to Choose

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

"Which session would you like to resume?
 
1. ses_451cd8ae... (12 messages, updated 2026-01-11)
2. ses_451a89e6... (5 messages, updated 2026-01-10)
3. ses_4518e90d... (8 messages, updated 2026-01-09)

Enter session number or ID:"

Step 3: Load Selected Session

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

1. Start OpenCode ACP:

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

1. Initialize:

{"jsonrpc":"2.0","id":0,"method":"initialize","params":{...}}

1. Load the session:

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

Note: session/load requires cwd and mcpServers parameters.

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

Resume Workflow Summary

function resumeSession(workdir):
    # List available sessions
    output = bash("opencode session list", workdir: workdir)
    sessions = parseSessionList(output)
    
    if sessions.empty:
        notify("No previous sessions found. Starting fresh.")
        return createNewSession(workdir)
    
    # Ask user to choose
    choice = askUser("Which session to resume?", sessions)
    selectedId = matchUserChoice(choice, sessions)
    
    # Start OpenCode and load session
    process = bash("opencode acp --cwd " + workdir, background: true, workdir: workdir)
    initialize(process)
    
    session_load(process, selectedId, workdir, mcpServers: [])
    
    notify("Session resumed. Conversation history loaded.")
    return process

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

bash(command: "opencode --version")

Returns something like: opencode version 1.1.13

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

Step 2: Check Latest Version

webfetch(url: "https://github.com/anomalyco/opencode/releases/latest", format: "text")

The redirect URL contains the latest version tag:

• Redirects to: https://github.com/anomalyco/opencode/releases/tag/v1.2.0
• Extract version from the URL path (e.g., 1.2.0)

Step 3: Compare and Update

If latest version > current version:

1. Stop all running OpenCode processes:

process.list()  # Find all "opencode acp" processes
   process.kill(sessionId) # For each running instance

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

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

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

Step 4: Verify Update

bash(command: "opencode --version")

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: curl -fsSL https://opencode.dev/install | bash

Update Workflow Summary

function updateOpenCode():
    current = bash("opencode --version")  # e.g., "1.1.13"
    
    latestPage = webfetch("https://github.com/anomalyco/opencode/releases/latest")
    latest = extractVersionFromRedirectUrl(latestPage)  # e.g., "1.2.0"
    
    if semverCompare(latest, current) > 0:
        # Stop all instances
        for process in process.list():
            if process.command.includes("opencode"):
                process.kill(process.sessionId)
        
        # Wait briefly for processes to terminate
        sleep(2 seconds)
        
        # Restart triggers auto-update
        bash("opencode acp", background: true)
        
        # Verify
        newVersion = bash("opencode --version")
        if newVersion != latest:
            notify("Auto-update may have failed. Manual update recommended.")
    else:
        notify("OpenCode is up to date: " + current)

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