hermes-ice/homelab/raw/articles/opencode/docs/sdk.md

type, agent, source, scraped, content_hash

type	agent	source	scraped	content_hash
agent-doc	OpenCode	https://opencode.ai/docs/sdk/	2026-04-28T21:02:14.594110+00:00	4720c626

SDK

Type-safe JS client for opencode server.

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

Install the SDK from npm:

npm install @opencode-ai/sdk

---

Create client

Create an instance of opencode:

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

---

Config

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:

import { createOpencode } from "@opencode-ai/sdk"
const opencode = await createOpencode({  hostname: "127.0.0.1",  port: 4096,  config: {    model: "anthropic/claude-3-5-sonnet-20241022",  },})
console.log(`Server running at ${opencode.server.url}`)
opencode.server.close()

Client only

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

import { createOpencodeClient } from "@opencode-ai/sdk"
const client = createOpencodeClient({  baseUrl: "http://localhost:4096",})

Option	Type	Description	Default
baseUrl	string	URL of the 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 return	false

---

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 can throw errors that you can catch and handle:

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

---

Structured Output

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

Basic Usage

const result = await client.session.prompt({  path: { id: sessionId },  body: {    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"],      },    },  },})
// Access the structured outputconsole.log(result.data.info.structured_output)// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }

Output Format Types

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

JSON Schema Format

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)

Error Handling

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

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

Best Practices

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

---

APIs

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

---

Global

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

---

Examples

const health = await client.global.health()console.log(health.data.version)

---

App

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

---

// Write a log entryawait client.app.log({  body: {    service: "my-app",    level: "info",    message: "Operation completed",  },})
// List available agentsconst agents = await client.app.agents()

---

Project

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

---

// List all projectsconst projects = await client.project.list()
// Get current projectconst currentProject = await client.project.current()

---

Path

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

---

// Get current path informationconst 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 } }

---

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({ 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	Returns Session
session.unshare({ path })	Unshare session	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	body.noReply: true returns UserMessage (context only). Default returns AssistantMessage with AI response. Supports body.outputFormat for structured output
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

---

// Create and manage sessionsconst session = await client.session.create({  body: { title: "My session" },})
const sessions = await client.session.list()
// Send a prompt messageconst result = await client.session.prompt({  path: { id: session.id },  body: {    model: { providerID: "anthropic", modelID: "claude-3-5-sonnet-20241022" },    parts: [{ type: "text", text: "Hello!" }],  },})
// Inject context without triggering AI response (useful for plugins)await client.session.prompt({  path: { id: session.id },  body: {    noReply: true,    parts: [{ type: "text", text: "You are a helpful assistant." }],  },})

---

Files

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	{ type: "raw"
file.status({ query? })	Get status for tracked files	File[]

find.files supports a few optional query fields:

• type: "file" or "directory"
• directory: override the project root for the search
• limit: max results (1–200)

---

// Search and read filesconst textResults = await client.find.text({  query: { pattern: "function.*opencode" },})
const files = await client.find.files({  query: { query: "*.ts", type: "file" },})
const directories = await client.find.files({  query: { query: "packages", type: "directory", limit: 20 },})
const content = await client.file.read({  query: { path: "src/index.ts" },})

---

TUI

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

---

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

---

Auth

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

---

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

---

Events

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

---

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