| title | SDK | |||||||
|---|---|---|---|---|---|---|---|---|
| url | https://opencode.ai/docs/sdk/ | |||||||
| source | crawler | |||||||
| fetched_at | 2026-02-14 12:04:49 -0300 | |||||||
| rendered_js | false | |||||||
| word_count | 651 | |||||||
| summary | This document provides a comprehensive guide and API reference for the opencode JS/TS SDK, detailing installation, client configuration, and the usage of type-safe server endpoints. It explains how to manage sessions, handle errors, and implement structured JSON output using JSON schemas. | |||||||
| tags |
|
|||||||
| category | reference |
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 the SDK from npm:
npminstall@opencode-ai/sdk
Create an instance of opencode:
import { createOpencode } from"@opencode-ai/sdk"
const { client } =awaitcreateOpencode()
This starts both a server and a client
OptionTypeDescriptionDefaulthostname``stringServer hostname127.0.0.1``port``numberServer port4096``signal``AbortSignalAbort signal for cancellationundefined``timeout``numberTimeout in ms for server start5000``config``ConfigConfiguration 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:
import { createOpencode } from"@opencode-ai/sdk"
constopencode=awaitcreateOpencode({
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()
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"
constclient=createOpencodeClient({
baseUrl: "http://localhost:4096",
})
OptionTypeDescriptionDefaultbaseUrl``stringURL of the serverhttp://localhost:4096``fetch``functionCustom fetch implementationglobalThis.fetch``parseAs``stringResponse parsing methodauto``responseStyle``stringReturn style: data or fields``fields``throwOnError``booleanThrow errors instead of returnfalse
The SDK includes TypeScript definitions for all API types. Import them directly:
importtype { Session, Message, Part } from"@opencode-ai/sdk"
All types are generated from the server’s OpenAPI specification and available in the types file.
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 asError).message)
}
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.
constresult=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 output
console.log(result.data.info.structured_output)
// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }
TypeDescriptiontextDefault. Standard text response (no structured output)json_schemaReturns validated JSON matching the provided schema
When using type: 'json_schema', provide:
FieldTypeDescriptiontype``'json_schema'Required. Specifies JSON schema modeschema``objectRequired. JSON Schema object defining the output structureretryCount``numberOptional. Number of validation retries (default: 2)
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)
}
- Provide clear descriptions in your schema properties to help the model understand what data to extract
- Use
requiredto 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.
MethodDescriptionResponseglobal.health()Check server health and version{ healthy: true, version: string }
consthealth=await client.global.health()
console.log(health.data.version)
MethodDescriptionResponseapp.log()Write a log entryboolean``app.agents()List all available agentsAgent[]
// Write a log entry
await client.app.log({
body: {
service: "my-app",
level: "info",
message: "Operation completed",
},
})
// List available agents
constagents=await client.app.agents()
MethodDescriptionResponseproject.list()List all projectsProject[]project.current()Get current projectProject
// List all projects
constprojects=await client.project.list()
// Get current project
constcurrentProject=await client.project.current()
MethodDescriptionResponsepath.get()Get current pathPath
// Get current path information
constpathInfo=await client.path.get()
MethodDescriptionResponseconfig.get()Get config infoConfigconfig.providers()List providers and default models{ providers:Provider[], default: { [key: string]: string } }
constconfig=await client.config.get()
const { providers, default: defaults } =await client.config.providers()
MethodDescriptionNotessession.list()List sessionsReturns Session[]session.get({ path })Get sessionReturns Sessionsession.children({ path })List child sessionsReturns Session[]session.create({ body })Create sessionReturns Sessionsession.delete({ path })Delete sessionReturns boolean``session.update({ path, body })Update session propertiesReturns Sessionsession.init({ path, body })Analyze app and create AGENTS.mdReturns boolean``session.abort({ path })Abort a running sessionReturns boolean``session.share({ path })Share sessionReturns Sessionsession.unshare({ path })Unshare sessionReturns Sessionsession.summarize({ path, body })Summarize sessionReturns boolean``session.messages({ path })List messages in a sessionReturns { info:Message, parts:Part[]}[]``session.message({ path })Get message detailsReturns { info:Message, parts:Part[]}``session.prompt({ path, body })Send prompt messagebody.noReply: true returns UserMessage (context only). Default returns AssistantMessage with AI response. Supports body.outputFormat for structured outputsession.command({ path, body })Send command to sessionReturns { info:AssistantMessage, parts:Part[]}``session.shell({ path, body })Run a shell commandReturns AssistantMessagesession.revert({ path, body })Revert a messageReturns Sessionsession.unrevert({ path })Restore reverted messagesReturns SessionpostSessionByIdPermissionsByPermissionId({ path, body })Respond to a permission requestReturns boolean
// Create and manage sessions
constsession=await client.session.create({
body: { title: "My session" },
})
constsessions=await client.session.list()
// Send a prompt message
constresult=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." }],
},
})
MethodDescriptionResponsefind.text({ query })Search for text in filesArray of match objects with path, lines, line_number, absolute_offset, submatches``find.files({ query })Find files and directories by namestring[] (paths)find.symbols({ query })Find workspace symbolsSymbol[]file.read({ query })Read a file{ type: "raw" | "patch", content: string }``file.status({ query? })Get status for tracked filesFile[]
find.files supports a few optional query fields:
type:"file"or"directory"directory: override the project root for the searchlimit: max results (1–200)
// Search and read files
consttextResults=await client.find.text({
query: { pattern: "function.*opencode" },
})
constfiles=await client.find.files({
query: { query: "*.ts", type: "file" },
})
constdirectories=await client.find.files({
query: { query: "packages", type: "directory", limit: 20 },
})
constcontent=await client.file.read({
query: { path: "src/index.ts" },
})
MethodDescriptionResponsetui.appendPrompt({ body })Append text to the promptboolean``tui.openHelp()Open the help dialogboolean``tui.openSessions()Open the session selectorboolean``tui.openThemes()Open the theme selectorboolean``tui.openModels()Open the model selectorboolean``tui.submitPrompt()Submit the current promptboolean``tui.clearPrompt()Clear the promptboolean``tui.executeCommand({ body })Execute a commandboolean``tui.showToast({ body })Show toast notificationboolean
// Control TUI interface
await client.tui.appendPrompt({
body: { text: "Add this to prompt" },
})
await client.tui.showToast({
body: { message: "Task completed", variant: "success" },
})
MethodDescriptionResponseauth.set({ ... })Set authentication credentialsboolean
await client.auth.set({
path: { id: "anthropic" },
body: { type: "api", key: "your-api-key" },
})
MethodDescriptionResponseevent.subscribe()Server-sent events streamServer-sent events stream
// Listen to real-time events
constevents=await client.event.subscribe()
forawait (consteventof events.stream) {
console.log("Event:", event.type, event.properties)
}