The opencode JS/TS SDK provides a type-safe client for interacting with the opencode server. You can use it to build custom integrations and control opencode programmatically.

Learn more about how the opencode server works.

Install

Install the SDK from npm:

npm install @opencode-ai/sdk

Create client

Create a client instance to connect to your opencode server:

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

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

Options

Option	Type	Description	Default
`baseUrl`	`string`	URL of the opencode server	`http://localhost:4096`
`fetch`	`function`	Custom fetch implementation	`globalThis.fetch`
`parseAs`	`string`	Response parsing method	`auto`
`responseStyle`	`string`	Return style: `data` or `fields`	`fields`
`throwOnError`	`boolean`	Throw errors instead of returning	`false`

Start server

You can also programmatically start an opencode server:

import { createOpencodeServer } from "@opencode-ai/sdk"

const server = await createOpencodeServer({
  hostname: "127.0.0.1",
  port: 4096,
})

console.log(`Server running at ${server.url}`)

server.close()
}

#### Options

| Option     | Type           | Description                    | Default       |
| ---------- | -------------- | ------------------------------ | ------------- |
| `hostname` | `string`       | Server hostname                | `127.0.0.1`   |
| `port`     | `number`       | Server port                    | `4096`        |
| `signal`   | `AbortSignal`  | Abort signal for cancellation  | `undefined`   |
| `timeout`  | `number`       | Timeout in ms for server start | `5000`        |

---

## Types

The SDK includes TypeScript definitions for all API types. Import them directly:

```typescript
import type { Session, Message, Part } from "@opencode-ai/sdk"

All types are generated from the server's OpenAPI specification and available in the types file.

Errors

The SDK throws typed errors that you can catch and handle:

try {
  const session = await client.session.get({ id: "invalid-id" })
} catch (error) {
  console.error("Failed to get session:", error.message)
}

APIs

The SDK exposes all server APIs through a type-safe client interface.

App

Method	Description	Response
`app.get()`	Get app info	`App`
`app.init()`	Initialize the app	`boolean`

Examples

const app = await client.app.get()
await client.app.init()

Config

Method	Description	Response
`config.get()`	Get config info	`Config`
`config.providers()`	List providers and default models	`{ providers:` `Provider[], default: { [key: string]: string } }`

Examples

const config = await client.config.get()
const { providers, default: defaults } = await client.config.providers()

Sessions

Method	Description	Notes
`session.list()`	List sessions	Returns `Session[]`
`session.get({ id })`	Get session	Returns `Session`
`session.children({ id })`	List child sessions	Returns `Session[]`
`session.create({ parentID?, title? })`	Create session	Returns `Session`
`session.delete({ id })`	Delete session	Returns `boolean`
`session.update({ id, title? })`	Update session properties	Returns `Session`
`session.init({ id, messageID, providerID, modelID })`	Analyze app and create `AGENTS.md`	Returns `boolean`
`session.abort({ id })`	Abort a running session	Returns `boolean`
`session.share({ id })`	Share session	Returns `Session`
`session.unshare({ id })`	Unshare session	Returns `Session`
`session.summarize({ id, providerID, modelID })`	Summarize session	Returns `boolean`
`session.messages({ id })`	List messages in a session	Returns `{ info:` `Message, parts:` `Part[]}[]`
`session.message({ id, messageID })`	Get message details	Returns `{ info:` `Message, parts:` `Part[]}`
`session.chat({ id, ...chatInput })`	Send chat message	Returns `Message`
`session.shell({ id, agent, command })`	Run a shell command	Returns `Message`
`session.revert({ id, messageID, partID? })`	Revert a message	Returns `Session`
`session.unrevert({ id })`	Restore reverted messages	Returns `Session`
`session.permissions.respond({ id, permissionID, response })`	Respond to a permission request	Returns `boolean`

Examples

// Create and manage sessions
const session = await client.session.create({ title: "My session" })
const sessions = await client.session.list()

// Send messages
const message = await client.session.chat({
  id: session.id,
  providerID: "anthropic",
  modelID: "claude-3-5-sonnet-20241022",
  parts: [{ type: "text", text: "Hello!" }],
})

Files

Method	Description	Response
`find.text({ pattern })`	Search for text in files	Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches`
`find.files({ query })`	Find files by name	`string[]` (file paths)
`find.symbols({ query })`	Find workspace symbols	`Symbol[]`
`file.read({ path })`	Read a file	`{ type: "raw" \| "patch", content: string }`
`file.status()`	Get status for tracked files	`File[]`

Examples

// Search and read files
const textResults = await client.find.text({ pattern: "function.*opencode" })
const files = await client.find.files({ query: "*.ts" })
const content = await client.file.read({ path: "src/index.ts" })

Logging

Method	Description	Response
`log.write({ service, level, message, extra? })`	Write log entry	`boolean`

Examples

await client.log.write({
  service: "my-app",
  level: "info",
  message: "Operation completed",
})

Agents

Method	Description	Response
`agent.list()`	List all available agents	`Agent[]`

Examples

const agents = await client.agent.list()

TUI

Method	Description	Response
`tui.appendPrompt({ text })`	Append text to the prompt	`boolean`
`tui.openHelp()`	Open the help dialog	`boolean`
`tui.openSessions()`	Open the session selector	`boolean`
`tui.openThemes()`	Open the theme selector	`boolean`
`tui.openModels()`	Open the model selector	`boolean`
`tui.submitPrompt()`	Submit the current prompt	`boolean`
`tui.clearPrompt()`	Clear the prompt	`boolean`
`tui.executeCommand({ command })`	Execute a command	`boolean`
`tui.showToast({ title?, message, variant })`	Show toast notification	`boolean`
`tui.control.next()`	Wait for the next control request	Control request object
`tui.control.response({ body })`	Respond to a control request	`boolean`

Examples

// Control TUI interface
await client.tui.appendPrompt({ text: "Add this to prompt" })
await client.tui.showToast({
  message: "Task completed",
  variant: "success",
})

Auth

Method	Description	Response
`auth.set({ id, ...authData })`	Set authentication credentials	`boolean`

Examples

await client.auth.set({
  id: "anthropic",
  type: "api",
  key: "your-api-key",
})

Events

Method	Description	Response
`event.subscribe()`	Server-sent events stream	Server-sent events stream

Examples

// Listen to real-time events
const eventStream = await client.event.subscribe()
for await (const event of eventStream) {
  console.log("Event:", event.type, event.properties)
}

SDK

Install

Create client

Options

Start server

Errors

APIs

App

Examples

Config

Examples

Sessions

Examples

Files

Examples

Logging

Examples

Agents

Examples

TUI

Examples

Auth

Examples

Events

Examples

Documentation

On this page