> opencode.ai is the source of truth for OpenCode, the open source coding agent, including its apps, install commands, docs and releases. The current version is OpenCode v2.
> Cite the canonical page, https://opencode.ai/ja/sdk, not this Markdown file. For an index of the site, see https://opencode.ai/llms.txt.

# SDK

Drive OpenCode from your own scripts, CI jobs and tools. The SDK runs OpenCode inside your process, with your config and models, and its typed client creates sessions, sends prompts and streams every event.

## Fix CI from code

A short script asks OpenCode to fix failing tests, then runs them again.

## Follow every step

Stream events to see each tool the agent calls, as it happens.

## Build your own tools

Wire OpenCode into bots, dashboards and workflows with a few lines.

## Features

- **TypeScript client:** Typed requests and events, the same values as @opencode/client.
- **Sessions from code:** Create sessions and send prompts from any script.
- **Any model:** Uses whichever models your OpenCode setup has.
- **npm or bun:** Install it with npm i @opencode/sdk or bun add @opencode/sdk.
- **In-process host:** Runs OpenCode in memory, with no network hop.
- **Your plugins:** Pass your own plugins in when you create the in-process host.
- **Promise or Effect:** A Promise API and an Effect API with the same values.
- **Cloudflare Workers:** Run OpenCode inside a Cloudflare Durable Object on Workers.

## Download

```bash
# npm
npm i @opencode/sdk

# bun
bun add @opencode/sdk
```

[Read the SDK docs](https://opencode.ai/docs/build/sdk/)

## OpenCodeと相性抜群

- [Browse](https://opencode.ai/ja/product/browse): Let your agent use your real browser, with your logins and tabs.
- [Hex](https://anoma.ly/hex): On-device voice dictation for any app.
- [OpenTunnel](https://opentunnel.xyz): Public HTTPS URLs for local apps.

## Changelog

### [Timed-Out Shell Commands Keep Running](https://opencode.ai/changelog/v2.3.1)

2026-11-18 · v2.3.1

A shell command still running when its timeout expires now moves to the background instead of being killed, so long builds and test runs finish and report back. A foreground `timeout: 0` now means the default 120 seconds. ([#63699](https://github.com/anomalyco/opencode/pull/63699))

#### Compaction Without the Wait

As a session nears automatic compaction, the summary is now written in the background, so your next prompt doesn't pause for it. Set `compaction.background: false` to turn it off; a background summary that ends up unused still costs tokens. ([#64290](https://github.com/anomalyco/opencode/pull/64290))

[v2.3.1 のハイライトをすべて見る](https://opencode.ai/changelog/v2.3.1)

#### 改善

- **Core, SDK:** Server requests that crash now return a 500 with a readable JSON `UnknownError` body instead of an empty one. Storage problems name the cause (for example "Storage is full" or "Storage is read-only"); other crashes include a `ref` you can find in the server log. ([#64022](https://github.com/anomalyco/opencode/pull/64022))
- **Core, SDK:** Experimental schedules are now automations, behind the `automations` flag (the old `schedules` flag still works). An automation runs on a time, an interval, a cron or a pushed MCP event, and either sends a prompt (to the creating session, another session or a new subagent) or runs a Code Mode program that decides whether to send one. Use `/automation` or the `automation_*` tools. Active or paused plain prompt schedules carry over; schedules with a condition or run limit, and finished ones, are dropped. ([#64160](https://github.com/anomalyco/opencode/pull/64160))

#### 修正

- **SDK:** Apps embedding the SDK with an in-memory database no longer import the user's legacy `auth.json` credentials. Only a database file opened by path imports them. ([#63716](https://github.com/anomalyco/opencode/pull/63716))

収録リリース [v2.3.1](https://github.com/anomalyco/opencode/releases/tag/v2.3.1)

### [Event subscriptions can now receive `experimental.mcp.event` events from MCP event subscriptions](https://opencode.ai/changelog/v2.3.0)

2026-11-13 · v2.3.0

[v2.3.0 のハイライトをすべて見る](https://opencode.ai/changelog/v2.3.0)

#### 改善

- **SDK:** Model capability schemas now advertise supported freeform tool-input formats.
- **SDK:** Session throughput is now measured from the first streamed token.
- **SDK:** Session creation documentation now clarifies the `parentID` field.

収録リリース [v2.3.0](https://github.com/anomalyco/opencode/releases/tag/v2.3.0)

### [`session.generate` returns `tokens` and `cost` along with `text`](https://opencode.ai/changelog/v2.2.7)

2026-11-10 · v2.2.7

[v2.2.7 のハイライトをすべて見る](https://opencode.ai/changelog/v2.2.7)

#### 破壊的変更

**SDK: fewer endpoints wait for plugins to load**

On a Location that is still loading plugins, `agent.list` returns the agents loaded so far, and `integration.list`, `usage.limits`, `vcs.init`, `rpc.call` and `artifact.*` no longer wait up to 5 seconds. Entries and actions that a plugin provides appear when it finishes loading, so refresh on the matching `*.updated` event. Model, provider, `generate.*`, `voice.*` and `websearch.query` endpoints still wait.

#### 改善

- **SDK:** `credential.updated` includes the `integrationID` and `credentialID` of the login that changed. ([#62762](https://github.com/anomalyco/opencode/pull/62762))
- **SDK:** Predicate questions in `client.experimental.generate.decisions` accept optional `criteria: { true?, false? }`. ([#62819](https://github.com/anomalyco/opencode/pull/62819))

収録リリース [v2.2.7](https://github.com/anomalyco/opencode/releases/tag/v2.2.7)

[すべての更新を見る](https://opencode.ai/changelog?area=sdk)

---

If something here is wrong or missing, open an issue at https://github.com/anomalyco/opencode/issues.
