Skip to content

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.

Features

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.

In your process

Runs OpenCode inside your process, with your config and models.

  • TypeScript clientTyped requests and events, the same values as @opencode/client.
  • Sessions from codeCreate sessions and send prompts from any script.
  • Any modelUses whichever models your OpenCode setup has.
  • npm or bunInstall it with npm i @opencode/sdk or bun add @opencode/sdk.
  • In-process hostRuns OpenCode in memory, with no network hop.
  • Your pluginsPass your own plugins in when you create the in-process host.
  • Promise or EffectA Promise API and an Effect API with the same values.
  • Cloudflare WorkersRun OpenCode inside a Cloudflare Durable Object on Workers.

  • npmnpm i @opencode/sdk
  • bunbun add @opencode/sdk
Read the SDK docs

Changelog

  1. v2.2.4

    Publish Interactive Artifacts

    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

    Improvements

    • SDKExtended client.experimental.persistentPty.update to rename terminals or clear a user title, and exposed userTitle plus persistent-pty.updated events.#60329
  2. v2.2.3

    Added lazy loading for stored image references when experimental.media_blob is enabled

    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

    Improvements

    • SDKPreserved partial LLMResponse output on AIError.partial when generation, object generation, or a tool loop fails.#60477
    • SDKUnified Effect and Promise tool declarations around tool(...), with optional output schemas and executable or declaration-only tools.#60407
    • SDKAdded typed OpenRouter debug, models, plugins, provider, and user options to the Responses route.#60044

    Fixes

    • SDKMatched the Promise AI client more closely to the Effect API and accepted typed tools in loops.#60465#60390
    • SDKKept tools whose execute handler can throw available to the AI client.#60431
    • SDKContinued polling queued media generations when providers return unknown intermediate statuses.#59988
    • SDKStopped sending an incompatible filename alongside file_url on OpenAI Responses requests.#60382
  3. v2.2.2

    Exposed SessionInfo.time.busy for the latest execution’s start time

    Improvements

    • SDKAdded if and until inputs for client.experimental.schedule.create, plus schedule check results and output fields.#60137
    • SDKAdded optional source metadata to prompt file attachments.
See all updates