SDK

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

Learn more about how the server works. For examples, check out the projects built by the community.

Install the SDK from npm:

Terminal

npm install @opencode-ai/sdk

Create an instance of opencode:

JavaScript

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

const { client } = await createOpencode()

This starts both a server and a client

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`
`config`	`Config`	Configuration object	`{}`

You can pass a configuration object to customize behavior. The instance still picks up your opencode.json, but you can override or add configuration inline:

JavaScript

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

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  config: {
    model: "anthropic/claude-sonnet-5-5",
  },
})

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

opencode.server.close()

If you already have a running instance of opencode, you can create a client instance to connect to it:

JavaScript

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

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

Options

Option	Type	Description	Default
`baseUrl`	`string`	URL of the server	None; set explicitly
`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 return	`false`

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.

By default, HTTP errors are returned in result.error. Set throwOnError: true to throw them instead. Network errors can still throw regardless of this option.

TypeScript

try {
  await client.session.get({ path: { id: "invalid-id" }, throwOnError: true })
} catch (error) {
  console.error("Failed to get session:", error)
}

You can request structured JSON output from the model by specifying a format with a JSON schema. The model will use a StructuredOutput tool to return validated JSON matching your schema.

Structured output is only available on the client exported from @opencode-ai/sdk/v2. This client takes flat parameters instead of path and body objects.

TypeScript

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

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

const result = await client.session.prompt(
  {
    sessionID: sessionId,
    parts: [{ type: "text", text: "Research Anthropic and provide company info" }],
    format: {
      type: "json_schema",
      schema: {
        type: "object",
        properties: {
          company: { type: "string", description: "Company name" },
          founded: { type: "number", description: "Year founded" },
          products: {
            type: "array",
            items: { type: "string" },
            description: "Main products",
          },
        },
        required: ["company", "founded"],
      },
    },
  },
  { throwOnError: true },
)

// Access the structured output
console.log(result.data.info.structured)
// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }

Type	Description
`text`	Default. Standard text response (no structured output)
`json_schema`	Returns validated JSON matching the provided schema

When using type: 'json_schema', provide:

Field	Type	Description
`type`	`'json_schema'`	Required. Specifies JSON schema mode
`schema`	`object`	Required. JSON Schema object defining the output structure
`retryCount`	`number`	Optional. Number of validation retries (default: 2)

If the model fails to produce valid structured output after all retries, the response will include a StructuredOutputError:

TypeScript

if (result.data.info.error?.name === "StructuredOutputError") {
  console.error("Failed to produce structured output:", result.data.info.error.data.message)
  console.error("Attempts:", result.data.info.error.data.retries)
}

Provide clear descriptions in your schema properties to help the model understand what data to extract
Use required to specify which fields must be present
Keep schemas focused - complex nested schemas may be harder for the model to fill correctly
Set appropriate retryCount - increase for complex schemas, decrease for simple ones

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

global.health() is only available on the @opencode-ai/sdk/v2 client.

Method	Description	Response
`global.health()`	Check server health and version	`{ healthy: true, version: string }`

Examples

JavaScript

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

const client = createOpencodeClient({ baseUrl: "http://localhost:4096" })
const health = await client.global.health({ throwOnError: true })
console.log(health.data.version)

Method	Description	Response
`app.log()`	Write a log entry	`boolean`
`app.agents()`	List all available agents	`Agent[]`

Examples

JavaScript

// Write a log entry
await client.app.log({
  body: {
    service: "my-app",
    level: "info",
    message: "Operation completed",
  },
})

// List available agents
const agents = await client.app.agents()

Method	Description	Response
`project.list()`	List all projects	`Project[]`

Examples

JavaScript

// List all projects
const projects = await client.project.list()

Method	Description	Response
`path.get()`	Get current path	`Path`

Examples

JavaScript

// Get current path information
const pathInfo = await client.path.get()

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

Examples

JavaScript

const config = await client.config.get()

const result = await client.config.providers({ throwOnError: true })
const { providers, default: defaults } = result.data

Method	Description	Notes
`session.list()`	List sessions	Returns `Session[]`
`session.get({ path })`	Get session	Returns `Session`
`session.children({ path })`	List child sessions	Returns `Session[]`
`session.create({ body })`	Create session	Returns `Session`
`session.delete({ path })`	Delete session	Returns `boolean`
`session.update({ path, body })`	Update session properties	Returns `Session`
`session.init({ path, body })`	Analyze app and create `AGENTS.md`	Returns `boolean`
`session.abort({ path })`	Abort a running session	Returns `boolean`
`session.share({ path })`	Share session	Sharing has been discontinued; this endpoint returns an error
`session.unshare({ path })`	Clear a stored share link	Returns `Session`
`session.summarize({ path, body })`	Summarize session	Returns `boolean`
`session.messages({ path })`	List messages in a session	Returns `{ info:` `Message, parts:` `Part[]}[]`
`session.message({ path })`	Get message details	Returns `{ info:` `Message, parts:` `Part[]}`
`session.prompt({ path, body })`	Send prompt message	Returns `{ info, parts }`. `body.noReply: true` adds context without an AI response. For structured output, use the `/v2` client
`session.command({ path, body })`	Send command to session	Returns `{ info:` `AssistantMessage, parts:` `Part[]}`
`session.shell({ path, body })`	Run a shell command	Returns `AssistantMessage`
`session.revert({ path, body })`	Revert a message	Returns `Session`
`session.unrevert({ path })`	Restore reverted messages	Returns `Session`
`postSessionByIdPermissionsByPermissionId({ path, body })`	Respond to a permission request	Returns `boolean`

Examples

JavaScript

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

const sessions = await client.session.list()

// Send a prompt message
const result = await client.session.prompt({
  path: { id: session.data.id },
  body: {
    model: { providerID: "anthropic", modelID: "claude-sonnet-5-5" },
    parts: [{ type: "text", text: "Hello!" }],
  },
})

// Inject context without triggering AI response (useful for plugins)
await client.session.prompt({
  path: { id: session.data.id },
  body: {
    noReply: true,
    parts: [{ type: "text", text: "You are a helpful assistant." }],
  },
})

Method	Description	Response
`find.text({ query })`	Search for text in files	Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches`
`find.files({ query })`	Find files and directories by name	`string[]` (paths)
`find.symbols({ query })`	Find workspace symbols	`Symbol[]`
`file.read({ query })`	Read a file	`FileContent`
`file.status({ query? })`	Get status for tracked files	`File[]`

The root client’s find.files supports these optional query fields:

dirs: "false" to search files only; otherwise directories are included
directory: override the project root for the search

The /v2 client additionally supports type ("file" or "directory") and limit (1–200), using flat parameters.

Examples

JavaScript

// Search and read files
const textResults = await client.find.text({
  query: { pattern: "function.*opencode" },
})

const files = await client.find.files({
  query: { query: ".ts", dirs: "false" },
})

const paths = await client.find.files({
  query: { query: "packages", dirs: "true" },
})

const content = await client.file.read({
  query: { path: "src/index.ts" },
})

Method	Description	Response
`tui.appendPrompt({ body })`	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({ body })`	Execute a command	`boolean`
`tui.showToast({ body })`	Show toast notification	`boolean`

Examples

JavaScript

// Control TUI interface
await client.tui.appendPrompt({
  body: { text: "Add this to prompt" },
})

await client.tui.showToast({
  body: { message: "Task completed", variant: "success" },
})

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

Examples

JavaScript

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

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

Examples

JavaScript

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

SDK

Install

Create client

Options

Config

Client only

Options

Types

Errors

Structured Output

Basic Usage

Output Format Types

JSON Schema Format

Error Handling

Best Practices

APIs

Global

Examples

App

Examples

Project

Examples

Path

Examples

Config

Examples

Sessions

Examples

Files

Examples

TUI

Examples

Auth

Examples

Events

Examples