OpenCode SDK API Reference

Complete API reference for @opencode-ai/sdk.

Table of Contents

  1. Initialization
  2. Session API
  3. Project API
  4. File API
  5. Find API
  6. Tool API
  7. Event API
  8. Config API
  9. Provider API
  10. MCP API
  11. TUI API
  12. PTY API
  13. Auth API

Initialization

createOpencode

Creates both an OpenCode client and starts a local server.

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

const { client, server } = await createOpencode({
  hostname?: string,    // Default: "127.0.0.1"
  port?: number,        // Default: 4096
  timeout?: number,     // Default: 5000ms
  config?: Config       // Custom config overrides
})

// Clean up
server.close()

createOpencodeClient

Creates only the client (connects to existing server).

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

const client = createOpencodeClient({
  baseUrl?: string,         // Default: "http://127.0.0.1:4096"
  directory?: string,       // Working directory
  throwOnError?: boolean,   // Throw on API errors
  responseStyle?: "data" | "fields"  // Response format
})

Session API

client.session.*

list

List all sessions.

const { data, error } = await client.session.list()
// data: Session[]

create

Create a new session.

const { data, error } = await client.session.create({
  body?: {
    title?: string,
    parentID?: string
  }
})
// data: Session

get

Get a specific session.

const { data, error } = await client.session.get({
  path: { id: string }
})
// data: Session

delete

Delete a session.

const { data, error } = await client.session.delete({
  path: { id: string }
})

update

Update session properties.

const { data, error } = await client.session.update({
  path: { id: string },
  body: {
    title?: string,
    pinned?: boolean
  }
})

prompt

Send a message to a session.

const { data, error } = await client.session.prompt({
  path: { id: string },
  body: {
    parts: Part[],           // Message content
    model?: {                // Optional model override
      providerID: string,
      modelID: string
    },
    noReply?: boolean        // Don't trigger AI response
  }
})

Part Types

type Part =
  | { type: "text", text: string }
  | { type: "file", path: string, content?: string }
  | { type: "image", url: string }

promptAsync

Send message and return immediately (async processing).

const { data, error } = await client.session.promptAsync({
  path: { id: string },
  body: {
    parts: Part[],
    model?: { providerID: string, modelID: string }
  }
})

messages

Get all messages for a session.

const { data, error } = await client.session.messages({
  path: { id: string }
})
// data: Message[]

message

Get a specific message.

const { data, error } = await client.session.message({
  path: { id: string, messageID: string }
})
// data: Message

command

Send a slash command.

const { data, error } = await client.session.command({
  path: { id: string },
  body: {
    command: string  // e.g., "/help", "/init"
  }
})

shell

Execute a shell command.

const { data, error } = await client.session.shell({
  path: { id: string },
  body: {
    command: string
  }
})

status

Get session status (idle, busy, etc.).

const { data, error } = await client.session.status({
  path: { id: string }
})

abort

Abort current session activity.

const { data, error } = await client.session.abort({
  path: { id: string }
})

fork

Fork a session at a specific message.

const { data, error } = await client.session.fork({
  path: { id: string },
  body: {
    messageID: string
  }
})

children

Get child sessions (forks).

const { data, error } = await client.session.children({
  path: { id: string }
})

share / unshare

Share or unshare a session.

const { data, error } = await client.session.share({
  path: { id: string }
})
// Returns share URL

const { data, error } = await client.session.unshare({
  path: { id: string }
})

diff

Get the git diff for session changes.

const { data, error } = await client.session.diff({
  path: { id: string }
})

revert / unrevert

Revert or restore messages.

const { data, error } = await client.session.revert({
  path: { id: string },
  body: { messageID: string }
})

const { data, error } = await client.session.unrevert({
  path: { id: string }
})

summarize

Generate session summary.

const { data, error } = await client.session.summarize({
  path: { id: string }
})

todo

Get todo list for session.

const { data, error } = await client.session.todo({
  path: { id: string }
})

init

Initialize AGENTS.md for project.

const { data, error } = await client.session.init({
  path: { id: string }
})

Project API

client.project.*

list

List all projects.

const { data, error } = await client.project.list()
// data: Project[]

current

Get current project.

const { data, error } = await client.project.current()
// data: Project

File API

client.file.*

list

List files in a directory.

const { data, error } = await client.file.list({
  query: {
    path: string,
    recursive?: boolean
  }
})

read

Read file content.

const { data, error } = await client.file.read({
  query: {
    path: string
  }
})

status

Get file status (git status).

const { data, error } = await client.file.status()

Find API

client.find.*

text

Search for text in files.

const { data, error } = await client.find.text({
  query: {
    query: string,
    path?: string,
    caseSensitive?: boolean,
    regex?: boolean
  }
})

files

Find files by name.

const { data, error } = await client.find.files({
  query: {
    query: string,
    path?: string
  }
})

symbols

Find code symbols.

const { data, error } = await client.find.symbols({
  query: {
    query: string
  }
})

Tool API

client.tool.*

ids

Get list of all tool IDs.

const { data, error } = await client.tool.ids()
// data: string[]

list

Get tools with JSON schemas for a provider/model.

const { data, error } = await client.tool.list({
  query: {
    providerID: string,
    modelID: string
  }
})

Event API

client.event.*

subscribe

Subscribe to server-sent events.

const result = await client.event.subscribe()

for await (const event of result.events) {
  // event.type: string
  // event.data: any
  console.log(event)
}

// Or with options
const result = await client.event.subscribe({
  query: { sessionID?: string }
})

Event Types

  • session.created
  • session.deleted
  • session.updated
  • message.created
  • message.updated
  • tool.started
  • tool.completed
  • permission.requested

Config API

client.config.*

get

Get current configuration.

const { data, error } = await client.config.get()

update

Update configuration.

const { data, error } = await client.config.update({
  body: {
    theme?: string,
    model?: { providerID: string, modelID: string }
  }
})

providers

List configured providers.

const { data, error } = await client.config.providers()

Provider API

client.provider.*

list

List available providers.

const { data, error } = await client.provider.list()

auth

Get authentication methods for providers.

const { data, error } = await client.provider.auth()

oauth.authorize

Start OAuth flow.

const { data, error } = await client.provider.oauth.authorize({
  path: { provider: string }
})

oauth.callback

Handle OAuth callback.

const { data, error } = await client.provider.oauth.callback({
  path: { provider: string },
  query: { code: string, state?: string }
})

MCP API

client.mcp.*

status

Get MCP server status.

const { data, error } = await client.mcp.status()

add

Dynamically add MCP server.

const { data, error } = await client.mcp.add({
  body: {
    name: string,
    command: string,
    args?: string[],
    env?: Record<string, string>
  }
})

TUI API

client.tui.*

Control the terminal UI programmatically.

appendPrompt

Append text to the prompt.

const { data, error } = await client.tui.appendPrompt({
  body: { text: string }
})

submitPrompt

Submit the current prompt.

const { data, error } = await client.tui.submitPrompt()

clearPrompt

Clear the prompt.

const { data, error } = await client.tui.clearPrompt()

showToast

Show a toast notification.

const { data, error } = await client.tui.showToast({
  body: {
    message: string,
    type?: "info" | "success" | "warning" | "error"
  }
})

openHelp / openSessions / openThemes / openModels

Open various dialogs.

await client.tui.openHelp()
await client.tui.openSessions()
await client.tui.openThemes()
await client.tui.openModels()

executeCommand

Execute a TUI command.

const { data, error } = await client.tui.executeCommand({
  body: { command: string }
})

PTY API

client.pty.*

Manage pseudo-terminal sessions.

list

const { data, error } = await client.pty.list()

create

const { data, error } = await client.pty.create({
  body: {
    cols?: number,
    rows?: number,
    cwd?: string
  }
})

get / update / remove / connect

await client.pty.get({ path: { id: string } })
await client.pty.update({ path: { id: string }, body: { cols, rows } })
await client.pty.remove({ path: { id: string } })
await client.pty.connect({ path: { id: string } })

Auth API

client.auth.*

set

Set authentication credentials.

const { data, error } = await client.auth.set({
  path: { provider: string },
  body: {
    type: "key" | "oauth",
    key?: string,
    access?: string,
    refresh?: string,
    expires?: number
  }
})

Type Imports

Import types directly from the SDK:

import type {
  Session,
  Message,
  Part,
  Project,
  Model,
  Provider,
  Permission,
  UserMessage,
  Auth,
  Config,
  Event
} from "@opencode-ai/sdk"

Error Handling

const { data, error, response } = await client.session.get({
  path: { id: "invalid" }
})

if (error) {
  console.error("Error:", error)
  console.error("Status:", response.status)
} else {
  console.log("Session:", data)
}

// Or with throwOnError
try {
  const client = createOpencodeClient({ throwOnError: true })
  const { data } = await client.session.get({ path: { id: "test" } })
} catch (e) {
  console.error("API Error:", e)
}
Edit this page on GitHub