SDK

El SDK JS/TS de opencode proporciona un cliente con tipos para interactuar con el servidor. salo para construir integraciones y controlar opencode mediante programacin.

Ms informacin sobre cmo funciona el servidor. Para ejemplos, consulta los proyectos construidos por la comunidad.

---

Instalacin

Instala el SDK desde npm:

npm install @opencode-ai/sdk

---

Crear cliente

Crea una instancia de opencode:

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

const { client } = await createOpencode()

Esto inicia tanto un servidor como un cliente

Opciones

Option	Type	Description	Default
hostname	string	Nombre de host del servidor	127.0.0.1
port	number	Puerto del servidor	4096
signal	AbortSignal	Seal de aborto para cancelacin	undefined
timeout	number	Tiempo de espera en ms para el inicio del servidor	5000
config	Config	Objeto de configuracin	{}

---

Config

Puedes pasar un objeto de configuracin para personalizar el comportamiento. La instancia todava recupera tu opencode.json, pero puedes anular o agregar configuracin en lnea:

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(`Servidor ejecutndose en ${opencode.server.url}`)

opencode.server.close()

Solo cliente

Si ya tienes una instancia de opencode en ejecucin, puedes crear una instancia de cliente para conectarte a ella:

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

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

Opciones

Option	Type	Description	Default
baseUrl	string	URL del servidor	http://localhost:4096
fetch	function	Implementacin fetch personalizada	globalThis.fetch
parseAs	string	Mtodo de anlisis de respuesta	auto
responseStyle	string	Estilo de retorno: data o fields	fields
throwOnError	boolean	Lanzar errores en lugar de retornar	false

---

Tipos

El SDK incluye definiciones TypeScript para todos los tipos de API. Impprtalos directamente:

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

Todos los tipos se generan desde la especificacin OpenAPI del servidor y estn disponibles en el archivo de tipos.

---

Errores

El SDK puede lanzar errores que puedes atrapar y manejar:

try {
  await client.session.get({ path: { id: "invalid-id" } })
} catch (error) {
  console.error("Fallo al obtener la sesin:", (error as Error).message)
}

---

API

El SDK expone todas las API del servidor a travs de un cliente con tipos.

---

Global

Method	Description	Response
global.health()	Verificar el estado del servidor y la versin	{ healthy: true, version: string }

---

Ejemplos

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

---

App

Method	Description	Response
app.log()	Escribir una entrada de registro	boolean
app.agents()	Listar todos los agentes disponibles	Agent[]

---

Ejemplos

// Escribir una entrada de registro
await client.app.log({
  body: {
    service: "my-app",
    level: "info",
    message: "Operacin completada",
  },
})

// Listar agentes disponibles
const agents = await client.app.agents()

---

Project

Method	Description	Response
project.list()	Listar todos los proyectos	Project[]
project.current()	Obtener el proyecto actual	Project

---

Ejemplos

// Listar todos los proyectos
const projects = await client.project.list()

// Obtener el proyecto actual
const currentProject = await client.project.current()

---

Path

Method	Description	Response
path.get()	Obtener la ruta actual	Path

---

Ejemplos

// Obtener informacin de la ruta actual
const pathInfo = await client.path.get()

---

Config

Method	Description	Response
config.get()	Obtener informacin de configuracin	Config
config.providers()	Listar proveedores y modelos por defecto	{ providers: Provider[], default: { [key: string]: string } }

---

Ejemplos

const config = await client.config.get()

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

---

Sessions

Method	Description	Notes
session.list()	Listar sesiones	Retorna Session[]
session.get({ path })	Obtener sesin	Retorna Session
session.children({ path })	Listar sesiones hijas	Retorna Session[]
session.create({ body })	Crear sesin	Retorna Session
session.delete({ path })	Eliminar sesin y todos sus datos	Retorna boolean
session.update({ path, body })	Actualizar propiedades de sesin	Retorna Session
session.init({ path, body })	Analizar app y crear AGENTS.md	Retorna boolean
session.abort({ path })	Abortar una sesin en ejecucin	Retorna boolean
session.share({ path })	Compartir sesin	Retorna Session
session.unshare({ path })	Dejar de compartir sesin	Retorna Session
session.summarize({ path, body })	Resumir la sesin	Retorna boolean
session.messages({ path })	Listar mensajes en una sesin	Retorna { info: Message, parts: Part[]}[]
session.message({ path })	Obtener detalles del mensaje	Retorna { info: Message, parts: Part[]}
session.prompt({ path, body })	Enviar mensaje de prompt	body.noReply: true retorna UserMessage (solo contexto). Por defecto retorna AssistantMessage con respuesta IA
session.command({ path, body })	Enviar comando a la sesin	Retorna { info: AssistantMessage, parts: Part[]}
session.shell({ path, body })	Ejecutar un comando shell	Retorna AssistantMessage
session.revert({ path, body })	Revertir un mensaje	Retorna Session
session.unrevert({ path })	Restaurar mensajes revertidos	Retorna Session
postSessionByIdPermissionsByPermissionId({ path, body })	Responder a una solicitud de permiso	Retorna boolean

---

Ejemplos

// Crear y gestionar sesiones
const session = await client.session.create({
  body: { title: "Mi sesin" },
})

const sessions = await client.session.list()

// Enviar un mensaje de prompt
const result = await client.session.prompt({
  path: { id: session.id },
  body: {
    model: { providerID: "anthropic", modelID: "claude-3-5-sonnet-20241022" },
    parts: [{ type: "text", text: "Hola!" }],
  },
})

// Inyectar contexto sin activar respuesta IA (til para plugins)
await client.session.prompt({
  path: { id: session.id },
  body: {
    noReply: true,
    parts: [{ type: "text", text: "Eres un asistente til." }],
  },
})

---

Files

Method	Description	Response
find.text({ query })	Buscar texto en archivos	Matriz de objetos de coincidencia con path, lines, line_number, absolute_offset, submatches
find.files({ query })	Encontrar archivos y directorios por nombre	string[] (rutas)
find.symbols({ query })	Encontrar smbolos del espacio de trabajo	Symbol[]
file.read({ query })	Leer un archivo	{ type: "raw" | "patch", content: string }
file.status({ query? })	Obtener estado para archivos rastreados	File[]

find.files admite algunos campos de consulta opcionales:

• type: "file" o "directory"
• directory: anular la raz del proyecto para la bsqueda
• limit: mx resultados (1-200)

---

Ejemplos

// Buscar y leer archivos
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 })	Aadir texto al prompt	boolean
tui.openHelp()	Abrir el dilogo de ayuda	boolean
tui.openSessions()	Abrir el selector de sesin	boolean
tui.openThemes()	Abrir el selector de temas	boolean
tui.openModels()	Abrir el selector de modelos	boolean
tui.submitPrompt()	Enviar el prompt actual	boolean
tui.clearPrompt()	Limpiar el prompt	boolean
tui.executeCommand({ body })	Ejecutar un comando	boolean
tui.showToast({ body })	Mostrar notificacin toast	boolean

---

Ejemplos

// Controlar la interfaz TUI
await client.tui.appendPrompt({
  body: { text: "Aadir esto al prompt" },
})

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

---

Auth

Method	Description	Response
auth.set({ ... })	Establecer credenciales de autenticacin	boolean

---

Ejemplos

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

---

Events

Method	Description	Response
event.subscribe()	Flujo de eventos enviados por el servidor	Flujo de eventos enviados por el servidor

---

Ejemplos

// Escuchar eventos en tiempo real
const events = await client.event.subscribe()
for await (const event of events.stream) {
  console.log("Evento:", event.type, event.properties)
}