SDK

L’SDK JS/TS di opencode fornisce un client type-safe per interagire con il server. Usalo per creare integrazioni e controllare opencode in modo programmatico.

Scopri di piu su come funziona il server. Per esempi, guarda i progetti creati dalla comunita.

Installa l’SDK da npm:

Terminale

npm install @opencode-ai/sdk

Crea un’istanza di opencode:

JavaScript

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

const { client } = await createOpencode()

Questo avvia sia un server sia un client

Opzioni

Opzione	Tipo	Descrizione	Predefinito
`hostname`	`string`	Hostname del server	`127.0.0.1`
`port`	`number`	Porta del server	`4096`
`signal`	`AbortSignal`	Segnale di abort per annullare	`undefined`
`timeout`	`number`	Timeout in ms per avvio server	`5000`
`config`	`Config`	Oggetto di configurazione	`{}`

Puoi passare un oggetto di configurazione per personalizzare il comportamento. L’istanza legge comunque opencode.json, ma puoi sovrascrivere o aggiungere configurazione inline:

JavaScript

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

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

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

opencode.server.close()

Se hai gia un’istanza di opencode in esecuzione, puoi creare un client per collegarti:

JavaScript

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

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

Opzioni

Opzione	Tipo	Descrizione	Predefinito
`baseUrl`	`string`	URL del server	`http://localhost:4096`
`fetch`	`function`	Implementazione fetch custom	`globalThis.fetch`
`parseAs`	`string`	Metodo di parsing della risposta	`auto`
`responseStyle`	`string`	Stile di ritorno: `data` o `fields`	`fields`
`throwOnError`	`boolean`	Lancia errori invece di restituirli	`false`

L’SDK include definizioni TypeScript per tutti i tipi API. Importale direttamente:

TypeScript

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

Tutti i tipi sono generati dalla specifica OpenAPI del server e disponibili nel file dei tipi.

L’SDK puo lanciare errori che puoi intercettare e gestire:

TypeScript

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

Puoi richiedere un output JSON strutturato dal modello specificando un format con uno schema JSON. Il modello usera un tool StructuredOutput per restituire JSON validato che corrisponde al tuo schema.

TypeScript

const result = await client.session.prompt({
  path: { id: sessionId },
  body: {
    parts: [{ type: "text", text: "Research Anthropic and provide company info" }],
    format: {
      type: "json_schema",
      schema: {
        type: "object",
        properties: {
          company: { type: "string", description: "Company name" },
          founded: { type: "number", description: "Year founded" },
          products: {
            type: "array",
            items: { type: "string" },
            description: "Main products",
          },
        },
        required: ["company", "founded"],
      },
    },
  },
})

// Access the structured output
console.log(result.data.info.structured_output)
// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }

Tipo	Descrizione
`text`	Predefinito. Risposta di testo standard (nessun output strutturato)
`json_schema`	Restituisce JSON validato che corrisponde allo schema fornito

Quando usi type: 'json_schema', fornisci:

Campo	Tipo	Descrizione
`type`	`'json_schema'`	Richiesto. Specifica la modalita schema JSON
`schema`	`object`	Richiesto. Oggetto JSON Schema che definisce la struttura dell’output
`retryCount`	`number`	Opzionale. Numero di tentativi di validazione (default: 2)

Se il modello non riesce a produrre un output strutturato valido dopo tutti i tentativi, la risposta includera un StructuredOutputError:

TypeScript

if (result.data.info.error?.name === "StructuredOutputError") {
  console.error("Failed to produce structured output:", result.data.info.error.message)
  console.error("Attempts:", result.data.info.error.retries)
}

Fornisci descrizioni chiare nelle proprieta del tuo schema per aiutare il modello a capire quali dati estrarre
Usa required per specificare quali campi devono essere presenti
Mantieni gli schemi focalizzati - schemi annidati complessi potrebbero essere piu difficili da compilare correttamente per il modello
Imposta un retryCount appropriato - aumenta per schemi complessi, diminuisci per quelli semplici

L’SDK espone tutte le API del server tramite un client type-safe.

Metodo	Descrizione	Risposta
`global.health()`	Controlla stato e versione server	`{ healthy: true, version: string }`

Esempi

JavaScript

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

Metodo	Descrizione	Risposta
`app.log()`	Scrive una voce di log	`boolean`
`app.agents()`	Elenca tutti gli agenti	`Agent[]`

Esempi

JavaScript

// 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()

Metodo	Descrizione	Risposta
`project.list()`	Elenca i progetti	`Project[]`

Esempi

JavaScript

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

Metodo	Descrizione	Risposta
`path.get()`	Percorso corrente	`Path`

Esempi

JavaScript

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

Metodo	Descrizione	Risposta
`config.get()`	Ottieni info config	`Config`
`config.providers()`	Elenca provider e modelli default	`{ providers:` `Provider[], default: { [key: string]: string } }`

Esempi

JavaScript

const config = await client.config.get()

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

Metodo	Descrizione	Note
`session.list()`	Elenca le sessioni	Returns `Session[]`
`session.get({ path })`	Ottieni una sessione	Returns `Session`
`session.children({ path })`	Elenca sessioni figlie	Returns `Session[]`
`session.create({ body })`	Crea una sessione	Returns `Session`
`session.delete({ path })`	Elimina una sessione	Returns `boolean`
`session.update({ path, body })`	Aggiorna proprieta della sessione	Returns `Session`
`session.init({ path, body })`	Analizza app e crea `AGENTS.md`	Returns `boolean`
`session.abort({ path })`	Interrompe una sessione in corso	Returns `boolean`
`session.share({ path })`	Condivide la sessione	Returns `Session`
`session.unshare({ path })`	Rimuove la condivisione	Returns `Session`
`session.summarize({ path, body })`	Riassume la sessione	Returns `boolean`
`session.messages({ path })`	Elenca i messaggi della sessione	Returns `{ info:` `Message, parts:` `Part[]}[]`
`session.message({ path })`	Ottieni dettagli di un messaggio	Returns `{ info:` `Message, parts:` `Part[]}`
`session.prompt({ path, body })`	Invia un prompt	`body.noReply: true` returns UserMessage (solo contesto). Di default ritorna `AssistantMessage` con risposta AI. Supporta `body.outputFormat` per output strutturato
`session.command({ path, body })`	Invia un comando alla sessione	Returns `{ info:` `AssistantMessage, parts:` `Part[]}`
`session.shell({ path, body })`	Esegue un comando shell	Returns `AssistantMessage`
`session.revert({ path, body })`	Ripristina un messaggio	Returns `Session`
`session.unrevert({ path })`	Ripristina messaggi revertiti	Returns `Session`
`postSessionByIdPermissionsByPermissionId({ path, body })`	Risponde a una richiesta permessi	Returns `boolean`

Esempi

JavaScript

// 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-sonnet-5-5" },
    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." }],
  },
})

Metodo	Descrizione	Risposta
`find.text({ query })`	Cerca testo nei file	Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches`
`find.files({ query })`	Trova file e directory per nome	`string[]` (paths)
`find.symbols({ query })`	Trova simboli nel workspace	`Symbol[]`
`file.read({ query })`	Legge un file	`{ type: "raw" \| "patch", content: string }`
`file.status({ query? })`	Stato dei file tracciati	`File[]`

find.files supporta alcuni campi query opzionali:

type: "file" or "directory"
directory: sovrascrive la root del progetto per la ricerca
limit: risultati massimi (1–200)

Esempi

JavaScript

// 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" },
})

Metodo	Descrizione	Risposta
`tui.appendPrompt({ body })`	Aggiunge testo al prompt	`boolean`
`tui.openHelp()`	Apre la finestra help	`boolean`
`tui.openSessions()`	Apre il selettore sessioni	`boolean`
`tui.openThemes()`	Apre il selettore temi	`boolean`
`tui.openModels()`	Apre il selettore modelli	`boolean`
`tui.submitPrompt()`	Invia il prompt corrente	`boolean`
`tui.clearPrompt()`	Pulisce il prompt	`boolean`
`tui.executeCommand({ body })`	Esegue un comando	`boolean`
`tui.showToast({ body })`	Mostra una notifica toast	`boolean`

Esempi

JavaScript

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

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

Metodo	Descrizione	Risposta
`auth.set({ ... })`	Imposta credenziali auth	`boolean`

Esempi

JavaScript

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

Metodo	Descrizione	Risposta
`event.subscribe()`	Stream di server-sent events	Stream di server-sent events

Esempi

JavaScript

// 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)
}

SDK

Installa

Crea un client

Opzioni

Configurazione

Solo client

Opzioni

Tipi

Errori

Output Strutturato

Uso Base

Tipi di Formato Output

Formato Schema JSON

Gestione Errori

Best Practices

API

Globale

Esempi

App

Esempi

Progetto

Esempi

Path

Esempi

Config

Esempi

Sessioni

Esempi

File

Esempi

TUI

Esempi

Autenticazione

Esempi

Eventi

Esempi