Skip to main content
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