opencode-acp-skill

A skill developed for clawdbot to control opencode via ACP (Agents Communication Protocol)

Note: This project is not built by the OpenCode team and we are not affiliated with them in any way. This is an independent community project.

GitHub: https://github.com/bjesuiter/opencode-acp-skill

How It Works

Clawdbot (or other SKILLS-compatible AI Environment)
    |
    +-- loads skill: src/skill/opencode-acp.md
    |
    +-- bash tool (background: true)
    |      +-- starts: opencode acp
    |
    +-- process tool
           +-- write: send JSON-RPC messages (stdin)
           +-- poll: receive JSON-RPC responses (stdout)

The skill teaches clawdbot how to communicate directly with OpenCode using the ACP protocol. No intermediate CLI layer - clawdbot becomes a native ACP client using its built-in bash and process tools.

Usage

Available Commands

Command	Description
Start OpenCode	Launch OpenCode in ACP mode as background process
Send message	Write JSON-RPC messages to OpenCode via stdin
Read response	Poll stdout for JSON-RPC responses
Stop OpenCode	Kill the OpenCode background process
List sessions	Show all available OpenCode sessions for a project
Resume session	Load a previous session (preserves conversation history)
Cancel operation	Stop a running prompt mid-execution
Check version	Get current OpenCode version
Update OpenCode	Check for updates and trigger auto-update

Examples

1. Starting a New Session

Ask clawdbot to start a fresh OpenCode session:

"Start a new OpenCode session in /path/to/my/project"

Clawdbot will:

1. Run opencode acp in background mode
2. Send the initialize handshake
3. Create a new session with session/new
4. Be ready to accept prompts

2. Resuming a Previous Session

Ask clawdbot to continue where you left off:

"Resume my OpenCode session in /path/to/my/project"

Clawdbot will:

1. Run opencode session list to show available sessions
2. Ask you which session to resume
3. Load the selected session with full conversation history

3. Sending a Prompt

Once a session is active:

"Ask OpenCode to refactor the auth module"

Clawdbot will:

1. Send the prompt via session/prompt
2. Poll for responses every 2 seconds
3. Collect streaming updates until completion

4. Cancelling an Operation

If OpenCode is taking too long:

"Cancel the current OpenCode operation"

Clawdbot will send a session/cancel notification.

5. Checking for Updates

"Check if OpenCode needs updating"

Clawdbot will:

1. Check current version via opencode --version
2. Compare with latest GitHub release
3. If outdated, restart OpenCode to trigger auto-update

Project Structure

src/skill/
  opencode-acp.md   # The skill file - clawdbot reads this

agent/
  SPEC.md           # Full technical specification

docs/acp/           # ACP protocol reference documentation

Useful Links

• Official ACP Website: https://agentcommunicationprotocol.dev/introduction/welcome => Note: as of 2026-01-11 (that's when I checked), ACP will me merged into A2A, so this is a legacy protocol. Only reason for me to implement is that OpenCode supports it right now and i want to connect my clawdbot to opencode.

• Official ACP Website for LLMs: https://agentclientprotocol.com/llms.txt

• ACP TypeScript Client Library: https://www.npmjs.com/package/@agentclientprotocol/sdk => Use this if building a CLI or programmatic ACP client in the future: bun add @agentclientprotocol/sdk

Feature Status

v1 (Complete)

• Skill file with ACP protocol instructions
• Start OpenCode via opencode acp
• Initialize ACP connection
• Create sessions (session/new)
• Send prompts (session/prompt)
• Poll for responses (2 second intervals)
• Cancel operations (session/cancel)
• Session persistence (session/list + session/load)
• Version checking and auto-update workflow

v2 (Future - Ideas generated by AI)

• Continuous polling option
• MCP server passthrough
• Permission request handling
• Mode switching