SDK

opencode JS/TS SDK は、サーバーと対話するためのタイプセーフなクライアントを提供します。 これを使用して、統合を構築し、opencodeをプログラムで制御します。

サーバーの仕組みについて詳しくは、 をご覧ください。たとえば、コミュニティによって構築された projects をチェックしてください。

---

インストール

npm から SDK をインストールします。

npm install @opencode-ai/sdk

---

クライアントの作成

opencodeのインスタンスを作成します。

import { createOpencode } from "@opencode-ai/sdk"

const { client } = await createOpencode()

これにより、サーバーとクライアントの両方が起動します

オプション

オプション	タイプ	説明	デフォルト
hostname	string	サーバーのホスト名	127.0.0.1
port	number	サーバーポート	4096
signal	AbortSignal	キャンセルのためのアボート信号	undefined
timeout	number	サーバー起動のタイムアウト (ミリ秒)	5000
config	Config	構成オブジェクト	{}

---

構成

構成オブジェクトを渡して動作をカスタマイズできます。インスタンスは引き続き opencode.json を取得しますが、設定をインラインでオーバーライドまたは追加することができます。

import { createOpencode } from "@opencode-ai/sdk"

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  config: {
    model: "anthropic/claude-3-5-sonnet-20241022",
  },
})

console.log(`Server running at ${opencode.server.url}`)

opencode.server.close()

クライアントのみ

すでに実行中のopencodeのインスタンスがある場合は、それに接続するためのクライアント インスタンスを作成できます。

import { createOpencodeClient } from "@opencode-ai/sdk"

const client = createOpencodeClient({
  baseUrl: "http://localhost:4096",
})

オプション

オプション	タイプ	説明	デフォルト
baseUrl	string	サーバーの URL	http://localhost:4096
fetch	function	カスタムフェッチの実装	globalThis.fetch
parseAs	string	応答解析方法	auto
responseStyle	string	戻り値のスタイル: data または fields	fields
throwOnError	boolean	返す代わりにエラーをスローする	false

---

種類

SDK には、すべての API タイプの TypeScript 定義が含まれています。それらを直接インポートします。

import type { Session, Message, Part } from "@opencode-ai/sdk"

すべてのタイプはサーバーの OpenAPI 仕様から生成され、タイプ ファイル で使用できます。

---

エラー

SDK は、キャッチして処理できるエラーをスローできます。

try {
  await client.session.get({ path: { id: "invalid-id" } })
} catch (error) {
  console.error("Failed to get session:", (error as Error).message)
}

---

API

SDK は、タイプセーフなクライアントを通じてすべてのサーバー API を公開します。

---

Global

方法	説明	応答
global.health()	サーバーの健全性とバージョンを確認する	{ healthy: true, version: string }

---

例

const health = await client.global.health()
console.log(health.data.version)

---

App

方法	説明	応答
app.log()	ログエントリを書き込む	boolean
app.agents()	利用可能なすべてのエージェントをリストする	Agent[]

---

例

// Write a log entry
await client.app.log({
  body: {
    service: "my-app",
    level: "info",
    message: "Operation completed",
  },
})

// List available agents
const agents = await client.app.agents()

---

Project

方法	説明	応答
project.list()	すべてのプロジェクトをリストする	Project[]
project.current()	現在のプロジェクトを取得	Project

---

例

// List all projects
const projects = await client.project.list()

// Get current project
const currentProject = await client.project.current()

---

Path

方法	説明	応答
path.get()	現在のパスを取得	Path

---

例

// Get current path information
const pathInfo = await client.path.get()

---

Config

方法	説明	応答
config.get()	構成情報を取得する	Config
config.providers()	プロバイダーとデフォルトのモデルをリストする	{ providers: Provider[], default: { [key: string]: string } }

---

例

const config = await client.config.get()

const { providers, default: defaults } = await client.config.providers()

---

Sessions

方法	説明	メモ
session.list()	セッションをリストする	戻り値 Session[]
session.get({ path })	セッションを取得	戻り値 Session
session.children({ path })	子セッションをリストする	戻り値 Session[]
session.create({ body })	セッションの作成	戻り値 Session
session.delete({ path })	セッションを削除	戻り値 boolean
session.update({ path, body })	セッションのプロパティを更新する	戻り値 Session
session.init({ path, body })	アプリを分析して AGENTS.md を作成する	戻り値 boolean
session.abort({ path })	実行中のセッションを中止する	戻り値 boolean
session.share({ path })	セッションを共有する	戻り値 Session
session.unshare({ path })	セッションの共有を解除	戻り値 Session
session.summarize({ path, body })	セッションを要約する	戻り値 boolean
session.messages({ path })	セッション内のメッセージをリストする	戻り値 { info: Message, parts: Part[]}[]
session.message({ path })	メッセージの詳細を取得する	戻り値 { info: Message, parts: Part[]}
session.prompt({ path, body })	プロンプトメッセージを送信する	body.noReply: true は UserMessage (コンテキストのみ) を返します。デフォルトでは、AI 応答を含む AssistantMessage を返します。
session.command({ path, body })	コマンドをセッションに送信	戻り値 { info: AssistantMessage, parts: Part[]}
session.shell({ path, body })	shell コマンドを実行する	戻り値 AssistantMessage
session.revert({ path, body })	メッセージを元に戻す	戻り値 Session
session.unrevert({ path })	元に戻したメッセージを復元する	戻り値 Session
postSessionByIdPermissionsByPermissionId({ path, body })	許可リクエストに応答する	戻り値 boolean

---

例

// Create and manage sessions
const session = await client.session.create({
  body: { title: "My session" },
})

const sessions = await client.session.list()

// Send a prompt message
const result = await client.session.prompt({
  path: { id: session.id },
  body: {
    model: { providerID: "anthropic", modelID: "claude-3-5-sonnet-20241022" },
    parts: [{ type: "text", text: "Hello!" }],
  },
})

// Inject context without triggering AI response (useful for plugins)
await client.session.prompt({
  path: { id: session.id },
  body: {
    noReply: true,
    parts: [{ type: "text", text: "You are a helpful assistant." }],
  },
})

---

Files

Method	Description	Response
find.text({ query })	Search for text in files	Array of match objects with path, lines, line_number, absolute_offset, submatches
find.files({ query })	Find files and directories by name	string[] (paths)
find.symbols({ query })	Find workspace symbols	Symbol[]
file.read({ query })	Read a file	{ type: "raw" | "patch", content: string }
file.status({ query? })	Get status for tracked files	File[]

find.files は、いくつかのオプションのクエリ フィールドをサポートしています。

• type: "file" または "directory"
• directory: 検索用のプロジェクト ルートをオーバーライドします。
• limit: 最大結果 (1 ～ 200)

---

例

// Search and read files
const textResults = await client.find.text({
  query: { pattern: "function.*opencode" },
})

const files = await client.find.files({
  query: { query: "*.ts", type: "file" },
})

const directories = await client.find.files({
  query: { query: "packages", type: "directory", limit: 20 },
})

const content = await client.file.read({
  query: { path: "src/index.ts" },
})

---

TUI

方法	説明	応答
tui.appendPrompt({ body })	プロンプトにテキストを追加します	boolean
tui.openHelp()	ヘルプダイアログを開く	boolean
tui.openSessions()	セッションセレクターを開く	boolean
tui.openThemes()	テーマセレクターを開く	boolean
tui.openModels()	モデルセレクターを開く	boolean
tui.submitPrompt()	現在のプロンプトを送信します	boolean
tui.clearPrompt()	プロンプトをクリア	boolean
tui.executeCommand({ body })	コマンドを実行する	boolean
tui.showToast({ body })	トースト通知を表示	boolean

---

例

// Control TUI interface
await client.tui.appendPrompt({
  body: { text: "Add this to prompt" },
})

await client.tui.showToast({
  body: { message: "Task completed", variant: "success" },
})

---

Auth

方法	説明	応答
auth.set({ ... })	認証資格情報を設定する	boolean

---

例

await client.auth.set({
  path: { id: "anthropic" },
  body: { type: "api", key: "your-api-key" },
})

---

Events

方法	説明	応答
event.subscribe()	サーバー送信イベント ストリーム	サーバー送信イベント ストリーム

---

例

// Listen to real-time events
const events = await client.event.subscribe()
for await (const event of events.stream) {
  console.log("Event:", event.type, event.properties)
}