SDK

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

---

Start server

You can also programmatically start an opencode server:

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

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

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

server.close()

---

Types

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

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)
}