SDK Overview

Build programmatic integrations with OpenCode using the JavaScript/TypeScript SDK

The OpenCode SDK provides a type-safe JavaScript/TypeScript client for programmatic interaction with the OpenCode server. Use it to build integrations, automate workflows, and control OpenCode from your own applications.

Features

• Type-safe API: Full TypeScript support with auto-generated types from OpenAPI specification
• Server Management: Start and manage OpenCode server instances programmatically
• Session Control: Create, manage, and interact with AI coding sessions
• Real-time Events: Subscribe to server-sent events for live updates
• File Operations: Search, read, and manage project files
• Configuration: Programmatically configure models, agents, and providers
• Plugin Development: Build custom tools and extensions

Installation

Install the SDK from npm:

npm install @opencode-ai/sdk

Or with other package managers:

yarn add @opencode-ai/sdk
pnpm add @opencode-ai/sdk
bun add @opencode-ai/sdk

Quick Start

Server + Client

Create a complete OpenCode instance with both server and client:

import { createOpencode } from '@opencode-ai/sdk'

const { client, server } = await createOpencode({
  hostname: '127.0.0.1',
  port: 4096,
  config: {
    model: 'anthropic/claude-3-5-sonnet-20241022',
  },
})

// Use the client
const health = await client.global.health()
console.log(`Server version: ${health.data.version}`)

// Clean up when done
server.close()

Client Only

Connect to an existing OpenCode server:

import { createOpencodeClient } from '@opencode-ai/sdk'

const client = createOpencodeClient({
  baseUrl: 'http://localhost:4096',
})

const sessions = await client.session.list()
console.log(`Active sessions: ${sessions.data.length}`)

Architecture

The SDK is organized into several namespaces:

• global: Server health and global events
• session: Session management and AI interactions
• project: Project information and navigation
• config: Configuration management
• file/find: File operations and search
• app: Application-level operations
• tui: Terminal UI control
• auth: Authentication management
• event: Real-time event subscriptions

Common Use Cases

Build Integrations

Connect OpenCode to other tools, CI/CD pipelines, or custom workflows:

const session = await client.session.create({
  body: { title: 'Automated Review' },
})

await client.session.prompt({
  path: { id: session.data.id },
  body: {
    parts: [{ type: 'text', text: 'Review recent changes' }],
  },
})

Automate Testing

Generate tests programmatically:

await client.session.command({
  path: { id: sessionId },
  body: {
    name: 'test',
    arguments: 'src/utils.ts',
  },
})

Custom Dashboards

Build monitoring dashboards with real-time updates:

const events = await client.event.subscribe()

for await (const event of events.stream) {
  if (event.type === 'session.updated') {
    updateDashboard(event.properties.info)
  }
}

Extract Structured Data

Use structured output to extract information:

const result = await client.session.prompt({
  path: { id: sessionId },
  body: {
    parts: [{ type: 'text', text: 'Analyze this codebase' }],
    format: {
      type: 'json_schema',
      schema: {
        type: 'object',
        properties: {
          languages: { type: 'array', items: { type: 'string' } },
          frameworks: { type: 'array', items: { type: 'string' } },
          complexity: { type: 'string', enum: ['low', 'medium', 'high'] },
        },
      },
    },
  },
})

const analysis = result.data.info.structured_output

Type Safety

All API responses and request parameters are fully typed:

import type { Session, Message, Part, Config } from '@opencode-ai/sdk'

// TypeScript will validate your code
const session: Session = await client.session.get({
  path: { id: 'session-id' },
})

const messages: { info: Message; parts: Part[] }[] = await client.session.messages({
  path: { id: session.data.id },
})

Error Handling

Handle errors gracefully:

try {
  const session = await client.session.get({
    path: { id: 'invalid-id' },
  })
} catch (error) {
  if (error instanceof Error) {
    console.error('Failed to get session:', error.message)
  }
}

Or configure the client to return errors instead of throwing:

const client = createOpencodeClient({
  baseUrl: 'http://localhost:4096',
  throwOnError: false,
})

const result = await client.session.get({
  path: { id: 'invalid-id' },
})

if (result.error) {
  console.error('Error:', result.error)
} else {
  console.log('Session:', result.data)
}

Next Steps

Client API

Learn about client creation and configuration

Configuration

Configure OpenCode programmatically

Types

Explore TypeScript types and interfaces

Plugin Development

Build custom tools and extensions