Develop

Build integrations and extend OpenCode with the SDK, server, plugins, and ecosystem.

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 in Server. For examples, check out the projects built by the community in Ecosystem.

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

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

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 a 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

JSON Schema Format

When using type: 'json_schema', provide:

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

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

App

// 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

// List all projects
const projects = await client.project.list()

// Get current project
const currentProject = await client.project.current()

Path

const pathInfo = await client.path.get()

Config

const config = await client.config.get()

const { providers, default: defaults } = await client.config.providers()

Sessions

// 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

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

// Control TUI interface
await client.tui.appendPrompt({
  body: { text: "Add this to prompt" },
})

await client.tui.showToast({
  body: { message: "Task completed", variant: "success" },
})

Auth

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

Events

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

Server

Interact with opencode server over HTTP.

The opencode serve command runs a headless HTTP server that exposes an OpenAPI endpoint that an opencode client can use.

Usage

opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]

Options

opencode serve --cors http://localhost:5173 --cors https://app.example.com

Authentication

Set OPENCODE_SERVER_PASSWORD to protect the server with HTTP basic auth. The username defaults to opencode, or set OPENCODE_SERVER_USERNAME to override it. This applies to both opencode serve and opencode web.

OPENCODE_SERVER_PASSWORD=your-password opencode serve

How it works

When you run opencode it starts a TUI and a server. The TUI is the client that talks to the server. The server exposes an OpenAPI 3.1 spec endpoint. This endpoint is also used to generate an SDK.

This architecture lets opencode support multiple clients and allows you to interact with opencode programmatically.

You can run opencode serve to start a standalone server. If you have the opencode TUI running, opencode serve will start a new server.

Connect to an existing server

When you start the TUI it randomly assigns a port and hostname. You can instead pass in the --hostname and --port flags. Then use this to connect to its server.

The /tui endpoint can be used to drive the TUI through the server. For example, you can prefill or run a prompt. This setup is used by the OpenCode IDE plugins.

Spec

The server publishes an OpenAPI 3.1 spec that can be viewed at, for example, http://localhost:4096/doc. Use the spec to generate clients or inspect request and response types. Or view it in a Swagger explorer.

APIs

The opencode server exposes the following APIs.

Global

Project

Path & VCS

Instance

Config

Provider

Sessions

Messages

Commands

Files

/find/file query parameters:

• query (required) — search string (fuzzy match)
• type (optional) — limit results to "file" or "directory"
• directory (optional) — override the project root for the search
• limit (optional) — max results (1–200)
• dirs (optional) — legacy flag ("false" returns only files)

Tools (Experimental)

LSP, Formatters & MCP

Agents

Logging

TUI

Auth

Events

Docs

Plugins

Write your own plugins to extend OpenCode.

Plugins allow you to extend OpenCode by hooking into various events and customizing behavior. You can create plugins to add new features, integrate with external services, or modify OpenCode's default behavior.

Use a plugin

There are two ways to load plugins.

From local files

Place JavaScript or TypeScript files in the plugin directory.

• .opencode/plugins/ — Project-level plugins
• ~/.config/opencode/plugins/ — Global plugins

Files in these directories are automatically loaded at startup.

From npm

Specify npm packages in your config file.

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "opencode-wakatime", "@my-org/custom-plugin"]
}

Both regular and scoped npm packages are supported.

Browse available plugins in the Ecosystem.

How plugins are installed

npm plugins are installed automatically using Bun at startup. Packages and their dependencies are cached in ~/.cache/opencode/node_modules/.

Local plugins are loaded directly from the plugin directory. To use external packages, you must create a package.json within your config directory (see Dependencies), or publish the plugin to npm and add it to your config.

Load order

Plugins are loaded from all sources and all hooks run in sequence. The load order is:

1. Global config (~/.config/opencode/opencode.json)
2. Project config (opencode.json)
3. Global plugin directory (~/.config/opencode/plugins/)
4. Project plugin directory (.opencode/plugins/)

Duplicate npm packages with the same name and version are loaded once. However, a local plugin and an npm plugin with similar names are both loaded separately.

Dependencies

Local plugins and custom tools can use external npm packages. Add a package.json to your config directory with the dependencies you need.

{
  "dependencies": {
    "shescape": "^2.1.0"
  }
}

OpenCode runs bun install at startup to install these. Your plugins and tools can then import them.

import { escape } from "shescape"
export const MyPlugin = async (ctx) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "bash") {
        output.args.command = escape(output.args.command)
      }
    },
  }
}

Create a plugin

Basic structure

A plugin is a JavaScript/TypeScript module that exports one or more plugin functions. Each function receives a context object and returns a hooks object.

export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
  console.log("Plugin initialized!")
  return {
    // Hook implementations go here
  }
}

The plugin function receives:

• project: The current project information.
• directory: The current working directory.
• worktree: The git worktree path.
• client: An opencode SDK client for interacting with the AI.
• $: Bun's shell API for executing commands.

TypeScript support

For TypeScript plugins, you can import types from the plugin package:

import type { Plugin } from "@opencode-ai/plugin"
export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // Type-safe hook implementations
  }
}

Events

Plugins can subscribe to events as seen below in the Examples section. Here is a list of the different events available.

Command Events: command.executed

File Events: file.edited, file.watcher.updated

Installation Events: installation.updated

LSP Events: lsp.client.diagnostics, lsp.updated

Message Events: message.part.removed, message.part.updated, message.removed, message.updated

Permission Events: permission.asked, permission.replied

Server Events: server.connected

Session Events: session.created, session.compacted, session.deleted, session.diff, session.error, session.idle, session.status, session.updated

Todo Events: todo.updated

Shell Events: shell.env

Tool Events: tool.execute.after, tool.execute.before

TUI Events: tui.prompt.append, tui.command.execute, tui.toast.show

Examples

Send notifications

Send notifications when certain events occur:

export const NotificationPlugin = async ({ project, client, $, directory, worktree }) => {
  return {
    event: async ({ event }) => {
      // Send notification on session completion
      if (event.type === "session.idle") {
        await $`osascript -e 'display notification "Session completed!" with title "opencode"'`
      }
    },
  }
}

We are using osascript to run AppleScript on macOS. Here we are using it to send notifications.

.env protection

Prevent opencode from reading .env files:

export const EnvProtection = async ({ project, client, $, directory, worktree }) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "read" && output.args.filePath.includes(".env")) {
        throw new Error("Do not read .env files")
      }
    },
  }
}

Inject environment variables

Inject environment variables into all shell execution (AI tools and user terminals):

export const InjectEnvPlugin = async () => {
  return {
    "shell.env": async (input, output) => {
      output.env.MY_API_KEY = "secret"
      output.env.PROJECT_ROOT = input.cwd
    },
  }
}

Custom tools

Plugins can also add custom tools to opencode:

import { type Plugin, tool } from "@opencode-ai/plugin"
export const CustomToolsPlugin: Plugin = async (ctx) => {
  return {
    tool: {
      mytool: tool({
        description: "This is a custom tool",
        args: {
          foo: tool.schema.string(),
        },
        async execute(args, context) {
          const { directory, worktree } = context
          return `Hello ${args.foo} from ${directory} (worktree: ${worktree})`
        },
      }),
    },
  }
}

The tool helper creates a custom tool that opencode can call. It takes a Zod schema function and returns a tool definition with:

• description: What the tool does
• args: Zod schema for the tool's arguments
• execute: Function that runs when the tool is called

Your custom tools will be available to opencode alongside built-in tools.

Logging

Use client.app.log() instead of console.log for structured logging:

export const MyPlugin = async ({ client }) => {
  await client.app.log({
    body: {
      service: "my-plugin",
      level: "info",
      message: "Plugin initialized",
      extra: { foo: "bar" },
    },
  })
}

Levels: debug, info, warn, error. See SDK documentation for details.

Compaction hooks

Customize the context included when a session is compacted:

import type { Plugin } from "@opencode-ai/plugin"
export const CompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // Inject additional context into the compaction prompt
      output.context.push(`## Custom Context
Include any state that should persist across compaction:
- Current task status
- Important decisions made
- Files being actively worked on`)
    },
  }
}

The experimental.session.compacting hook fires before the LLM generates a continuation summary. Use it to inject domain-specific context that the default compaction prompt would miss.

You can also replace the compaction prompt entirely by setting output.prompt:

import type { Plugin } from "@opencode-ai/plugin"
export const CustomCompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // Replace the entire compaction prompt
      output.prompt = `You are generating a continuation prompt for a multi-agent swarm session.
Summarize:
1. The current task and its status
2. Which files are being modified and by whom
3. Any blockers or dependencies between agents
4. The next steps to complete the work

Format as a structured prompt that a new agent can use to resume work.`
    },
  }
}

When output.prompt is set, it completely replaces the default compaction prompt. The output.context array is ignored in this case.

Ecosystem

Projects and integrations built with OpenCode.

A collection of community projects built on OpenCode.

You can also check out awesome-opencode and opencode.cafe, a community that aggregates the ecosystem and community.

Plugins

Projects

Agents