SDK

El SDK opencode JS/TS proporciona un cliente con seguridad de tipos para interactuar con el servidor. Úselo para crear integraciones y controlar opencode mediante programación.

Más información sobre cómo funciona el servidor. Para ver ejemplos, consulte los proyectos creados por la comunidad.

---

Instalar

Instale el SDK desde npm:

npm install @opencode-ai/sdk

---

Crear cliente

Cree una instancia de opencode:

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

const { client } = await createOpencode()

Esto inicia tanto un servidor como un cliente.

Opciones

Opción	Tipo	Descripción	Predeterminado
hostname	string	Nombre de host del servidor	127.0.0.1
port	number	Puerto del servidor	4096
signal	AbortSignal	Señal de aborto para cancelación	undefined
timeout	number	Tiempo de espera en ms para inicio del servidor	5000
config	Config	Objeto de configuración	{}

---

Configuración

Puede pasar un objeto de configuración para personalizar el comportamiento. La instancia aún recoge su opencode.json, pero puede anular o agregar configuración en línea:

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

Solo cliente

Si ya tiene una instancia en ejecución de opencode, puede crear una instancia de cliente para conectarse a ella:

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

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

Opciones

Opción	Tipo	Descripción	Predeterminado
baseUrl	string	URL del servidor	http://localhost:4096
fetch	function	Implementación de recuperación personalizada	globalThis.fetch
parseAs	string	Método de análisis de respuesta	auto
responseStyle	string	Estilo de devolución: data o fields	fields
throwOnError	boolean	Lanzar errores en lugar de devolver	false

---

Tipos

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

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

Todos los tipos se generan a partir de la especificación OpenAPI del servidor y están disponibles en el archivo de tipos.

---

Errores

El SDK puede generar errores que puedes detectar y manejar:

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

---

API

El SDK expone todas las API del servidor a través de un cliente con seguridad de tipos.

---

Global

Método	Descripción	Respuesta
global.health()	Verificar el estado y la versión del servidor	{ healthy: true, version: string }

---

Ejemplos

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

---

Aplicación

Método	Descripción	Respuesta
app.log()	Escribe una entrada de registro	boolean
app.agents()	Listar todos los agentes disponibles	Agent[]

---

Ejemplos

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

---

Proyecto

Método	Descripción	Respuesta
project.list()	Listar todos los proyectos	Project[]
project.current()	Obtener proyecto actual	Project

---

Ejemplos

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

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

---

Camino

Método	Descripción	Respuesta
path.get()	Obtener ruta actual	Path

---

Ejemplos

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

---

Configuración

Método	Descripción	Respuesta
config.get()	Obtener información de configuración	Config
config.providers()	Lista de proveedores y modelos predeterminados	{ providers: Provider[], default: { [key: string]: string } }

---

Ejemplos

const config = await client.config.get()

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

---

Sesiones

Método	Descripción	Notas
session.list()	Listar sesiones	Devuelve Session[]
session.get({ path })	Obtener sesión	Devuelve Session
session.children({ path })	Listar sesiones infantiles	Devuelve Session[]
session.create({ body })	Crear sesión	Devuelve Session
session.delete({ path })	Eliminar sesión	Devuelve boolean
session.update({ path, body })	Actualizar propiedades de sesión	Devuelve Session
session.init({ path, body })	Analizar aplicación y crear AGENTS.md	Devuelve boolean
session.abort({ path })	Cancelar una sesión en ejecución	Devuelve boolean
session.share({ path })	Compartir sesión	Devuelve Session
session.unshare({ path })	Dejar de compartir sesión	Devuelve Session
session.summarize({ path, body })	Resumir sesión	Devuelve boolean
session.messages({ path })	Listar mensajes en una sesión	Devuelve { info: Message, parts: Part[]}[]
session.message({ path })	Obtener detalles del mensaje	Devuelve { info: Message, parts: Part[]}
session.prompt({ path, body })	Enviar mensaje rápido	body.noReply: true devuelve UserMessage (solo contexto). El valor predeterminado devuelve AssistantMessage con respuesta de IA
session.command({ path, body })	Enviar comando a la sesión	Devuelve { info: AssistantMessage, parts: Part[]}
session.shell({ path, body })	Ejecute un comando de shell	Devuelve AssistantMessage
session.revert({ path, body })	Revertir un mensaje	Devuelve Session
session.unrevert({ path })	Restaurar mensajes revertidos	Devuelve Session
postSessionByIdPermissionsByPermissionId({ path, body })	Responder a una solicitud de permiso	Devuelve boolean

---

Ejemplos

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

---

Archivos

Método	Descripción	Respuesta
find.text({ query })	Buscar texto en archivos	Matriz de objetos coincidentes con path, lines, line_number, absolute_offset, submatches
find.files({ query })	Buscar archivos y directorios por nombre	string[] (rutas)
find.symbols({ query })	Buscar símbolos del espacio de trabajo	Symbol[]
file.read({ query })	Leer un archivo	{ type: "raw" | "patch", content: string }
file.status({ query? })	Obtener el estado de los archivos rastreados	File[]

find.files admite algunos campos de consulta opcionales:

• type: "file" o "directory"
• directory: anula la raíz del proyecto para la búsqueda.
• limit: resultados máximos (1–200)

---

Ejemplos

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

Método	Descripción	Respuesta
tui.appendPrompt({ body })	Agregar texto al mensaje	boolean
tui.openHelp()	Abra el cuadro de diálogo de ayuda	boolean
tui.openSessions()	Abrir el selector de sesiones	boolean
tui.openThemes()	Abra el selector de temas	boolean
tui.openModels()	Abrir el selector de modelo	boolean
tui.submitPrompt()	Enviar el mensaje actual	boolean
tui.clearPrompt()	Borrar el mensaje	boolean
tui.executeCommand({ body })	Ejecutar un comando	boolean
tui.showToast({ body })	Mostrar notificación del brindis	boolean

---

Ejemplos

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

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

---

Autenticación

Método	Descripción	Respuesta
auth.set({ ... })	Establecer credenciales de autenticación	boolean

---

Ejemplos

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

---

Eventos

Método	Descripción	Respuesta
event.subscribe()	Transmisión de eventos enviados por el servidor	Transmisión de eventos enviados por el servidor

---

Ejemplos

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