---
slug: "opencode-acp-skill"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/bjesuiter/opencode-acp-skill@main/README.md"
repo: "https://github.com/bjesuiter/opencode-acp-skill"
source_file: "README.md"
branch: "main"
---
# 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)
- [x] Skill file with ACP protocol instructions
- [x] Start OpenCode via `opencode acp`
- [x] Initialize ACP connection
- [x] Create sessions (`session/new`)
- [x] Send prompts (`session/prompt`)
- [x] Poll for responses (2 second intervals)
- [x] Cancel operations (`session/cancel`)
- [x] Session persistence (`session/list` + `session/load`)
- [x] Version checking and auto-update workflow

### v2 (Future - Ideas generated by AI)
- [ ] Continuous polling option
- [ ] MCP server passthrough
- [ ] Permission request handling
- [ ] Mode switching