9.9 KiB
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: Terminal window
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", })
Options 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 output console.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
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
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[] Examples
// 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()
Project Method Description Response project.list() List all projects Project[] project.current() Get current project Project Examples
// List all projects const projects = await client.project.list()
// Get current project const currentProject = await client.project.current()
Path Method Description Response path.get() Get current path Path Examples
// Get current path information const pathInfo = await client.path.get()
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({ 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 Examples
// Create and manage sessions const session = await client.session.create({ body: { title: "My session" }, })
const sessions = await client.session.list()
// Send a prompt message const 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" | "patch", content: string } 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)
Examples
// Search and read files const 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 Examples
// Control TUI interface await 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 Examples
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 Examples
// 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) }