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

    session.generate returns tokens and cost along with text

    See all highlights in v2.2.7

    Breaking changes

    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.

    #62796#63040

    Improvements

    • SDKcredential.updated includes the integrationID and credentialID of the login that changed.#62762
    • SDKPredicate questions in client.experimental.generate.decisions accept optional criteria: { true?, false? }.#62819
  2. v2.2.6

    Improvements

    See all highlights in v2.2.6

    Improvements

    • SDKAdded client.experimental.job.list() and its Effect equivalent for listing background shell, subagent, and image jobs, with session, descendant, kind, and status filters.#60698
    • SDKServer embedders can provide a custom fetch implementation for OpenCode HTTP, model, web, and remote MCP traffic.#61582
  3. 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

    See all highlights in v2.2.4

    Improvements

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