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

## Changelog

### [Publish Interactive Artifacts](https://opencode.ai/changelog/v2.2.4)

2026-10-30 · v2.2.4

Enable `"experimental": { "artifacts": true }` in `opencode.json` to let agents publish, update, and serve HTML or static artifacts through the built-in local provider or plugin-provided storage. ([#60351](https://github.com/anomalyco/opencode/pull/60351))

#### Melhorias

- **SDK:** Extended `client.experimental.persistentPty.update` to rename terminals or clear a user title, and exposed `userTitle` plus `persistent-pty.updated` events. ([#60329](https://github.com/anomalyco/opencode/pull/60329))

Lançado em [v2.2.4](https://github.com/anomalyco/opencode/releases/tag/v2.2.4)

### [Added lazy loading for stored image references when `experimental.media_blob` is enabled](https://opencode.ai/changelog/v2.2.3)

2026-10-30 · v2.2.3

Added lazy loading for stored image references when `experimental.media_blob` is enabled. Images are downloaded only for previews, while undo, revert, fork, and prompt recall restore referenced attachments safely. ([#60116](https://github.com/anomalyco/opencode/pull/60116))

#### Melhorias

- **SDK:** Preserved partial `LLMResponse` output on `AIError.partial` when generation, object generation, or a tool loop fails. ([#60477](https://github.com/anomalyco/opencode/pull/60477))
- **SDK:** Unified Effect and Promise tool declarations around `tool(...)`, with optional output schemas and executable or declaration-only tools. ([#60407](https://github.com/anomalyco/opencode/pull/60407))
- **SDK:** Added typed OpenRouter `debug`, `models`, `plugins`, `provider`, and `user` options to the Responses route. ([#60044](https://github.com/anomalyco/opencode/pull/60044))

#### Correções

- **SDK:** Matched the Promise AI client more closely to the Effect API and accepted typed tools in loops. ([#60465](https://github.com/anomalyco/opencode/pull/60465), [#60390](https://github.com/anomalyco/opencode/pull/60390))
- **SDK:** Kept tools whose `execute` handler can throw available to the AI client. ([#60431](https://github.com/anomalyco/opencode/pull/60431))
- **SDK:** Continued polling queued media generations when providers return unknown intermediate statuses. ([#59988](https://github.com/anomalyco/opencode/pull/59988))
- **SDK:** Stopped sending an incompatible `filename` alongside `file_url` on OpenAI Responses requests. ([#60382](https://github.com/anomalyco/opencode/pull/60382))

Lançado em [v2.2.3](https://github.com/anomalyco/opencode/releases/tag/v2.2.3)

### [Exposed `SessionInfo.time.busy` for the latest execution’s start time](https://opencode.ai/changelog/v2.2.2)

2026-10-29 · v2.2.2

#### Melhorias

- **SDK:** Added `if` and `until` inputs for `client.experimental.schedule.create`, plus schedule check results and output fields. ([#60137](https://github.com/anomalyco/opencode/pull/60137))
- **SDK:** Added optional source metadata to prompt file attachments.

Lançado em [v2.2.2](https://github.com/anomalyco/opencode/releases/tag/v2.2.2)

[Ver todas as novidades](https://opencode.ai/changelog?area=sdk)

## More from Anomaly

- [Hex](https://anoma.ly/hex): On-device voice dictation for any app.
- [OpenTunnel](https://opentunnel.xyz): Public HTTPS URLs for local apps.
- [OpenTUI](https://opentui.com): A library for terminal user interfaces.

---

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