opencode-acp

Files (130)

• SKILL.md
• openai.yaml · agents/
• announcements-acp-agent-registry-stabilized.md · resources/auto/
• announcements-acp-v2-draft.md · resources/auto/
• announcements-additional-directories-stabilized.md · resources/auto/
• announcements-boolean-config-option-stabilized.md · resources/auto/
• announcements-elicitation-stabilized.md · resources/auto/
• announcements-implementation-information.md · resources/auto/
• announcements-logout-method-stabilized.md · resources/auto/
• announcements-message-id-stabilized.md · resources/auto/
• announcements-model-config-category-stabilized.md · resources/auto/
• announcements-request-cancellation-stabilized.md · resources/auto/
• announcements-sdk-1-0-releases.md · resources/auto/
• announcements-sergey-ignatov-lead-maintainer.md · resources/auto/
• announcements-session-close-stabilized.md · resources/auto/
• announcements-session-config-options-stabilized.md · resources/auto/
• announcements-session-delete-stabilized.md · resources/auto/
• announcements-session-info-update-stabilized.md · resources/auto/
• announcements-session-list-stabilized.md · resources/auto/
• announcements-session-resume-stabilized.md · resources/auto/
• announcements-session-usage-stabilized.md · resources/auto/
• announcements-tool-call-name-stabilized.md · resources/auto/
• announcements-transports-working-group.md · resources/auto/
• brand.md · resources/auto/
• community-code-of-conduct.md · resources/auto/
• community-communication.md · resources/auto/
• community-contributing.md · resources/auto/
• community-governance.md · resources/auto/
• community-working-interest-groups.md · resources/auto/
• get-started-agents.md · resources/auto/
• get-started-architecture.md · resources/auto/
• get-started-clients.md · resources/auto/
• get-started-introduction.md · resources/auto/
• get-started-registry.md · resources/auto/
• libraries-community.md · resources/auto/
• libraries-java.md · resources/auto/
• libraries-kotlin.md · resources/auto/
• libraries-python.md · resources/auto/
• libraries-rust.md · resources/auto/
• libraries-testing.md · resources/auto/
• libraries-typescript.md · resources/auto/
• llms.txt · resources/auto/
• protocol-v1-agent-plan.md · resources/auto/
• protocol-v1-authentication.md · resources/auto/
• protocol-v1-cancellation.md · resources/auto/
• protocol-v1-content.md · resources/auto/
• protocol-v1-elicitation.md · resources/auto/
• protocol-v1-extensibility.md · resources/auto/
• protocol-v1-file-system.md · resources/auto/
• protocol-v1-initialization.md · resources/auto/
• protocol-v1-overview.md · resources/auto/
• protocol-v1-prompt-turn.md · resources/auto/
• protocol-v1-schema.md · resources/auto/
• protocol-v1-session-config-options.md · resources/auto/
• protocol-v1-session-delete.md · resources/auto/
• protocol-v1-session-list.md · resources/auto/
• protocol-v1-session-modes.md · resources/auto/
• protocol-v1-session-setup.md · resources/auto/
• protocol-v1-slash-commands.md · resources/auto/
• protocol-v1-terminals.md · resources/auto/
• …and 70 more

SKILL.md (first lines)

# OpenCode ACP Skill

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

**See also:** `/opencode` - for driving the OpenCode CLI interactively (commands, agents, tools, MCP, config) rather than over ACP.

## Metadata

- For ACP Protocol Docs (for Agents/LLMs): [Introduction](resources/auto/get-started-introduction.md) and [Protocol Overview](resources/auto/protocol-v1-overview.md)
- GitHub Repo: [bjesuiter/opencode-acp-skill](https://github.com/bjesuiter/opencode-acp-skill)
- Issue Tracker: [bjesuiter/opencode-acp-skill issues](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: "<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

```bash
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:

```json
{
  "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

```json
{
  "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

```json
{
  "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)

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

No response expected - this is a notification.

## State to Track

From MAHDTech/agent-skills, MIT.

More from MAHDTech/agent-skills