opencode-sdk

OpenCode JavaScript/TypeScript SDK (@opencode-ai/sdk)

📚 Official Docs: For the latest information, always refer to the official documentation: https://opencode.ai/docs/sdk/

Type-safe JavaScript/TypeScript client for the OpenCode server. Use it to build integrations, automate workflows, and control OpenCode programmatically.

All types are auto-generated from the server's OpenAPI 3.1 specification and available in the types file.

---

Installation

npm install @opencode-ai/sdk
# or
bun add @opencode-ai/sdk

---

Two Client Modes

Full Lifecycle (createOpencode)

Starts an OpenCode server and returns a connected client. Use this when you own the server lifecycle.

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

const { client, server } = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  timeout: 5000,
  config: {
    model: "anthropic/claude-3-5-sonnet-20241022",
  },
})

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

// Use the client...

server.close()

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

The instance still picks up your opencode.json, but inline config overrides or adds to it. The returned server object has a .url property and a .close() method to shut down the server process.

Client Only (createOpencodeClient)

Connects to an already-running OpenCode server. Use this when the server is managed externally (e.g., opencode serve or a TUI instance).

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

const client = createOpencodeClient({
  baseUrl: "http://localhost:4096",
  throwOnError: true,
  responseStyle: "data",
})