Skip to content

opencode-integration.md

Latest commit

 

History

History
151 lines (119 loc) · 4.98 KB

opencode-integration.md

File metadata and controls

151 lines (119 loc) · 4.98 KB
Raw

OpenCode Server Integration

Overview

ClawCode integrates with the OpenCode AI coding server to orchestrate automated coding tasks. The integration is implemented in packages/opencode-client using the official @opencode-ai/sdk.

Prerequisites

  1. OpenCode CLI installed — npm i -g opencode or via your preferred method.
  2. Start the server — opencode serve (defaults to port 4096).
  3. Set authentication credentials via environment variables: 
    OPENCODE_SERVER_URL=http://localhost:4096
OPENCODE_SERVER_USERNAME=admin
OPENCODE_SERVER_PASSWORD=your-password

Architecture

┌─────────────┐     HTTP/SSE      ┌─────────────────┐
│  ClawCode    │ ◄──────────────► │  OpenCode Server │
│  Orchestrator│                   │  (port 4096)     │
│  (Elysia API)│                   │                  │
└──────┬───────┘                   └────────┬─────────┘
       │                                     │
       │  uses                               │  manages
       ▼                                     ▼
┌──────────────┐                   ┌─────────────────┐
│  opencode-   │                   │  AI Provider    │
│  client pkg  │                   │  (Claude, etc.) │
└──────────────┘                   └─────────────────┘

API Endpoints Used

Method Endpoint Purpose
GET /global/health Server health check
POST /session Create a new coding session
GET /session/:id Get session details
GET /session List all sessions
DELETE /session/:id Delete a session
POST /session/:id/message Send a synchronous prompt
POST /session/:id/prompt_async Send an async prompt (fire-and-forget)
POST /session/:id/abort Abort a running session
GET /session/:id/message List messages in a session
GET /session/:id/message/:msgId Get a specific message
GET /event Subscribe to global SSE event stream

Authentication

OpenCode server uses HTTP Basic Authentication:

import { OpenCodeClient } from "@repo/opencode-client";

const client = new OpenCodeClient({
  baseUrl: "http://localhost:4096",
  username: "admin",
  password: "your-password",
});

Session Lifecycle

stateDiagram-v2
    [*] --> Created: createSession()
    Created --> Prompting: sendPrompt()
    Prompting --> Idle: Response received
    Idle --> Prompting: sendPrompt()
    Idle --> Completed: Task finished
    Prompting --> Aborted: abortSession()
    Idle --> Aborted: abortSession()
    Completed --> [*]
    Aborted --> [*]
Loading

Creating a Session

const session = await client.createSession();
// session.id, session.status available

Sending Prompts

// Synchronous — waits for full response
const result = await client.sendPrompt(session.id, "Fix the bug in auth.ts", {
  model: "claude-sonnet-4-20250514",
});
// result.messages contains the response messages

// The client also supports abort
await client.abortSession(session.id);

Subscribing to Events (SSE)

for await (const event of client.subscribeToEvents()) {
  console.log(event.type, event.properties);
  // Events: session.updated, message.updated, message.part.updated, etc.
}

Waiting for Idle

// Poll until session reaches idle state
const session = await client.waitForIdle(sessionId, {
  pollIntervalMs: 1000,
  maxWaitMs: 300_000,
});

Package Exports

The @repo/opencode-client package exports:

  • OpenCodeClient — Main client class
  • OpenCodeError — Typed error with statusCode
  • Config types — OpenCodeClientConfig, CreateSessionOptions, SendPromptOptions, PromptResult, OpenCodeSSEEvent, EventCallback, ErrorCallback
  • SDK re-exports — Session, Message, Part, TextPart, ToolPart, ErrorPart, StepStartPart, StepFinishPart, SessionStatus, Event (as OpenCodeEvent)

Environment Variables

Variable Default Description
OPENCODE_SERVER_URL http://localhost:4096 OpenCode server base URL
OPENCODE_SERVER_USERNAME — Basic auth username
OPENCODE_SERVER_PASSWORD — Basic auth password
OPENCODE_REQUEST_TIMEOUT 30000 HTTP request timeout (ms)

Error Handling

All client methods throw OpenCodeError on failure:

import { OpenCodeError } from "@repo/opencode-client";

try {
  await client.sendPrompt(sessionId, "...");
} catch (err) {
  if (err instanceof OpenCodeError) {
    console.error(`HTTP ${err.statusCode}: ${err.message}`);
  }
}