SDK

Typsicherer JS-Client fr opencode-Server.

Das opencode JS/TS SDK stellt einen typsicheren Client fr die Interaktion mit dem Server bereit. Verwenden Sie es, um Integrationen zu erstellen und opencode programmgesteuert zu steuern.

Weitere Informationen ber die Funktionsweise des Servers. Beispiele finden Sie in den von der Gemeinschaft erstellten Projekten.

Installation

Installieren Sie das SDK von npm:

npm install @opencode-ai/sdk

Client erstellen

Erstellen Sie eine Instanz von opencode:

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

const { client } = await createOpencode()

Dadurch werden sowohl ein Server als auch ein Client gestartet

Optionen

Option	Type	Description	Default
`hostname`	`string`	Server-Hostname	`127.0.0.1`
`port`	`number`	Server-Port	`4096`
`signal`	`AbortSignal`	Abort-Signal fr Abbruch	`undefined`
`timeout`	`number`	Timeout in ms fr Serverstart	`5000`
`config`	`Config`	Konfigurationsobjekt	`{}`

Config

Sie knnen ein Konfigurationsobjekt bergeben, um das Verhalten anzupassen. Die Instanz ruft weiterhin Ihre opencode.json ab, Sie knnen jedoch Konfigurationen inline berschreiben oder hinzufgen:

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 luft unter ${opencode.server.url}`)

opencode.server.close()

Nur Client

Wenn Sie bereits eine ausgefhrte Instanz von opencode haben, knnen Sie eine Client-Instanz erstellen, um sich damit zu verbinden:

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

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

Optionen

Option	Type	Description	Default
`baseUrl`	`string`	URL des Servers	`http://localhost:4096`
`fetch`	`function`	Benutzerdefinierte fetch-Implementierung	`globalThis.fetch`
`parseAs`	`string`	Antwort-Parsing-Methode	`auto`
`responseStyle`	`string`	Rckgabe-Stil: `data` oder `fields`	`fields`
`throwOnError`	`boolean`	Fehler werfen statt zurckgeben	`false`

Typen

Das SDK enthlt TypeScript-Definitionen fr alle API-Typen. Importieren Sie sie direkt:

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

Alle Typen werden aus der OpenAPI-Spezifikation des Servers generiert und sind in der Typdatei verfgbar.

Fehler

Das SDK kann Fehler werfen, die Sie abfangen und behandeln knnen:

try {
  await client.session.get({ path: { id: "invalid-id" } })
} catch (error) {
  console.error("Fehler beim Abrufen der Sitzung:", (error as Error).message)
}

APIs

Das SDK macht alle Server-APIs ber einen typsicheren Client verfgbar.

Global

Method	Description	Response
`global.health()`	Server-Status und Version prfen	`{ healthy: true, version: string }`

Beispiele

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

App

Method	Description	Response
`app.log()`	Log-Eintrag schreiben	`boolean`
`app.agents()`	Alle verfgbaren Agents auflisten	`Agent[]`

Beispiele

// Log-Eintrag schreiben
await client.app.log({
  body: {
    service: "my-app",
    level: "info",
    message: "Vorgang abgeschlossen",
  },
})

// Verfgbare Agents auflisten
const agents = await client.app.agents()

Project

Method	Description	Response
`project.list()`	Alle Projekte auflisten	`Project[]`
`project.current()`	Aktuelles Projekt abrufen	`Project`

Beispiele

// Alle Projekte auflisten
const projects = await client.project.list()

// Aktuelles Projekt abrufen
const currentProject = await client.project.current()

Path

Method	Description	Response
`path.get()`	Aktuellen Pfad abrufen	`Path`

Beispiele

// Aktuelle Pfadinformationen abrufen
const pathInfo = await client.path.get()

Config

Method	Description	Response
`config.get()`	Konfigurations-Informationen abrufen	`Config`
`config.providers()`	Anbieter und Standardmodelle auflisten	`{ providers:` `Provider[], default: { [key: string]: string } }`

Beispiele

const config = await client.config.get()

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

Sessions

Method	Description	Notes
`session.list()`	Sitzungen auflisten	Gibt `Session[]` zurck
`session.get({ path })`	Sitzung abrufen	Gibt `Session` zurck
`session.children({ path })`	Kindersitzungen auflisten	Gibt `Session[]` zurck
`session.create({ body })`	Sitzung erstellen	Gibt `Session` zurck
`session.delete({ path })`	Sitzung und alle ihre Daten lschen	Gibt `boolean` zurck
`session.update({ path, body })`	Sitzungseigenschaften aktualisieren	Gibt `Session` zurck
`session.init({ path, body })`	App analysieren und `AGENTS.md` erstellen	Gibt `boolean` zurck
`session.abort({ path })`	Eine laufende Sitzung abbrechen	Gibt `boolean` zurck
`session.share({ path })`	Sitzung teilen	Gibt `Session` zurck
`session.unshare({ path })`	Freigabe der Sitzung aufheben	Gibt `Session` zurck
`session.summarize({ path, body })`	Sitzung zusammenfassen	Gibt `boolean` zurck
`session.messages({ path })`	Nachrichten in einer Sitzung auflisten	Gibt `{ info:` `Message, parts:` `Part[]}[]` zurck
`session.message({ path })`	Nachrichtendetails abrufen	Gibt `{ info:` `Message, parts:` `Part[]``} zurck
`session.prompt({ path, body })`	Prompt-Nachricht senden	`body.noReply: true` gibt UserMessage zurck (nur Kontext). Standard gibt `AssistantMessage` mit KI-Antwort zurck
`session.command({ path, body })`	Befehl an Sitzung senden	Gibt `{ info:` `AssistantMessage, parts:` `Part[]``} zurck
`session.shell({ path, body })`	Shell-Befehl ausfhren	Gibt `AssistantMessage` zurck
`session.revert({ path, body })`	Nachricht zurcknehmen	Gibt `Session` zurck
`session.unrevert({ path })`	Alle zurckgenommenen Nachrichten wiederherstellen	Gibt `Session` zurck
`postSessionByIdPermissionsByPermissionId({ path, body })`	Auf eine Berechtigungsanfrage antworten	Gibt `boolean` zurck

Beispiele

// Sitzungen erstellen und verwalten
const session = await client.session.create({
  body: { title: "Meine Sitzung" },
})

const sessions = await client.session.list()

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

// Kontext injizieren, ohne KI-Antwort auszulsen (ntzlich fr Plugins)
await client.session.prompt({
  path: { id: session.id },
  body: {
    noReply: true,
    parts: [{ type: "text", text: "Du bist ein hilfreicher Assistent." }],
  },
})

Files

Method	Description	Response
`find.text({ query })`	Text in Dateien suchen	Array von bereinstimmungsobjekten mit `path`, `lines`, `line_number`, `absolute_offset`, `submatches`
`find.files({ query })`	Dateien und Verzeichnisse nach Name finden	`string[]` (Pfade)
`find.symbols({ query })`	Arbeitsbereich-Symbole finden	`Symbol[]`
`file.read({ query })`	Eine Datei lesen	`{ type: "raw" \| "patch", content: string }`
`file.status({ query? })`	Status fr verfolgte Dateien abrufen	`File[]`

find.files untersttzt einige optionale Abfragefelder:

type: "file" oder "directory"
directory: Stammverzeichnis fr die Suche berschreiben
limit: Max Ergebnisse (1-200)

Beispiele

// Dateien suchen und lesen
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

Method	Description	Response
`tui.appendPrompt({ body })`	Text an Prompt anhngen	`boolean`
`tui.openHelp()`	Hilfe-Dialog ffnen	`boolean`
`tui.openSessions()`	Sitzungs-Auswahl ffnen	`boolean`
`tui.openThemes()`	Themen-Auswahl ffnen	`boolean`
`tui.openModels()`	Modellauswahl ffnen	`boolean`
`tui.submitPrompt()`	Aktuellen Prompt absenden	`boolean`
`tui.clearPrompt()`	Prompt lschen	`boolean`
`tui.executeCommand({ body })`	Befehl ausfhren	`boolean`
`tui.showToast({ body })`	Toast-Benachrichtigung anzeigen	`boolean`

Beispiele

// TUI-Schnittstelle steuern
await client.tui.appendPrompt({
  body: { text: "Dies zum Prompt hinzufgen" },
})

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

Auth

Method	Description	Response
`auth.set({ ... })`	Authentifizierungs-Anmeldedaten festlegen	`boolean`

Beispiele

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

Events

Method	Description	Response
`event.subscribe()`	Server-Sent-Events-Stream	Server-Sent-Events-Stream

Beispiele

// Echtzeit-Events abonnieren
const events = await client.event.subscribe()
for await (const event of events.stream) {
  console.log("Event:", event.type, event.properties)
}