OpenCode SDK for Elixir

An unofficial Elixir SDK for OpenCode that mirrors the JS SDK (@opencode-ai/sdk). The client and types are generated from the OpenCode OpenAPI spec.

hex.pm link: https://hex.pm/packages/opencode_sdk/

Installation

Add opencode_sdk to your dependencies in mix.exs:

def deps do
  [
    {:opencode_sdk, "~> 0.1.1"}
  ]
end

Quickstart

Start an OpenCode server and get a connected client:

{:ok, %{client: client, server: server}} = OpenCode.create()

{:ok, health} = OpenCode.Generated.Operations.global_health(client)
IO.inspect(health, label: "health")

OpenCode.close(%{server: server})

Connect to an existing server:

client = OpenCode.create_client(base_url: "http://127.0.0.1:4096")
{:ok, projects} = OpenCode.Generated.Operations.project_list(client)

Create API

`OpenCode.create/1` options

OpenCode.create/1 forwards to OpenCode.create_server/1 and returns %{client, server}.

Option	Type	Description	Default
`:hostname`	`String.t()`	Server hostname	`"127.0.0.1"`
`:port`	`integer()`	Server port	`4096`
`:timeout`	`integer()`	Startup timeout in ms	`5000`
`:config`	`map()`	Config passed via `OPENCODE_CONFIG_CONTENT`	`%{}`

`OpenCode.create_client/1` options

Option	Type	Description	Default
`:base_url`	`String.t()`	OpenCode server URL	`"http://127.0.0.1:4096"`
`:directory`	`String.t()`	Project directory sent via `x-opencode-directory`	`nil`
`:headers`	`map() \| keyword()`	Extra HTTP headers	`[]`
`:timeout`	`integer() \| :infinity`	Request timeout	`:infinity`

Common Workflows

Sessions and prompts

{:ok, session} =
  OpenCode.Generated.Operations.session_create(%{title: "SDK walkthrough"}, client)

{:ok, reply} =
  OpenCode.Generated.Operations.session_prompt(
    session.id,
    %{
      parts: [%{type: "text", text: "Summarize this project in 3 bullets."}]
    },
    client
  )

IO.inspect(reply.info)

Real-time events (SSE)

{:ok, %{stream: stream}} = OpenCode.Generated.Operations.event_subscribe(client)

Enum.each(stream, fn event ->
  IO.inspect(event.type, label: "event")
end)

TUI process lifecycle

{:ok, tui} = OpenCode.create_tui(project: "/path/to/project")
OpenCode.Tui.close(tui)

Capability Guide

The generated operations module includes much more than sessions. Key groups:

App: app_agents/1, app_log/2, app_skills/1
Projects and config: project_*, config_*, provider_*
Files and search: file_*, find_*, path_get/1
Session control: session_*, part_*, permission_*, question_*
MCP: mcp_*, mcp_auth_*
PTY: pty_*
TUI control endpoints: tui_*

Examples:

# Permissions
{:ok, pending} = OpenCode.Generated.Operations.permission_list(client)

# Questions
{:ok, questions} = OpenCode.Generated.Operations.question_list(client)

# MCP status
{:ok, mcp} = OpenCode.Generated.Operations.mcp_status(client)

# PTY sessions
{:ok, ptys} = OpenCode.Generated.Operations.pty_list(client)

# Providers
{:ok, providers} = OpenCode.Generated.Operations.provider_list(client)

Types and Docs

All OpenAPI types are generated under OpenCode.Generated.* (for example, OpenCode.Generated.Session).

API functions and types are documented in generated module docs, primarily:

OpenCode
OpenCode.Generated.Operations
OpenCode.Generated.* type modules

Regenerating

The OpenAPI spec is at priv/opencode_openapi.json. Regenerate the client with:

mix opencode.gen.client --spec priv/opencode_openapi.json

Note

This project is unofficial and is not affiliated with the OpenCode team.