SDK

O SDK JS/TS do opencode fornece um cliente seguro em tipos para interagir com o servidor. Use-o para construir integrações e controlar o opencode programaticamente.

Saiba mais sobre como o servidor funciona. Para exemplos, confira os projetos construídos pela comunidade.

Instale o SDK a partir do npm:

Terminal

npm install @opencode-ai/sdk

Crie uma instância do opencode:

JavaScript

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

const { client } = await createOpencode()

Isso inicia tanto um servidor quanto um cliente.

Opções

Opção	Tipo	Descrição	Padrão
`hostname`	`string`	Nome do host do servidor	`127.0.0.1`
`port`	`number`	Porta do servidor	`4096`
`signal`	`AbortSignal`	Sinal de abortar para cancelamento	`undefined`
`timeout`	`number`	Tempo limite em ms para iniciar o servidor	`5000`
`config`	`Config`	Objeto de configuração	`{}`

Você pode passar um objeto de configuração para personalizar o comportamento. A instância ainda pega seu opencode.json, mas você pode substituir ou adicionar configuração 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 você já tem uma instância do opencode em execução, pode criar uma instância de cliente para se conectar a ela:

JavaScript

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

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

Opções

Opção	Tipo	Descrição	Padrão
`baseUrl`	`string`	URL do servidor	`http://localhost:4096`
`fetch`	`function`	Implementação de fetch personalizada	`globalThis.fetch`
`parseAs`	`string`	Método de análise da resposta	`auto`
`responseStyle`	`string`	Estilo de retorno: `data` ou `fields`	`fields`
`throwOnError`	`boolean`	Lançar erros em vez de retornar	`false`

O SDK inclui definições TypeScript para todos os tipos da API. Importe-os diretamente:

TypeScript

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

Todos os tipos são gerados a partir da especificação OpenAPI do servidor e estão disponíveis no arquivo de tipos.

O SDK pode lançar erros que você pode capturar e tratar:

TypeScript

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

Você pode solicitar uma saída JSON estruturada do modelo especificando um format com um esquema JSON. O modelo usará uma ferramenta StructuredOutput para retornar um JSON validado correspondente ao seu esquema.

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

// Acessar a saída estruturada
console.log(result.data.info.structured_output)
// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }

Tipo	Descrição
`text`	Padrão. Resposta de texto padrão (sem saída estruturada)
`json_schema`	Retorna JSON validado correspondente ao esquema fornecido

Ao usar type: 'json_schema', forneça:

Campo	Tipo	Descrição
`type`	`'json_schema'`	Obrigatório. Especifica o modo de esquema JSON
`schema`	`object`	Obrigatório. Objeto JSON Schema definindo a estrutura de saída
`retryCount`	`number`	Opcional. Número de tentativas de validação (padrão: 2)

Se o modelo falhar em produzir uma saída estruturada válida após todas as tentativas, a resposta incluirá um 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)
}

Forneça descrições claras nas propriedades do seu esquema para ajudar o modelo a entender quais dados extrair
Use required para especificar quais campos devem estar presentes
Mantenha os esquemas focados - esquemas aninhados complexos podem ser mais difíceis para o modelo preencher corretamente
Defina um retryCount apropriado - aumente para esquemas complexos, diminua para os simples

O SDK expõe todas as APIs do servidor através de um cliente seguro em tipos.

Método	Descrição	Resposta
`global.health()`	Verificar a saúde e versão do servidor	`{ healthy: true, version: string }`

Exemplos

JavaScript

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

Método	Descrição	Resposta
`app.log()`	Escrever uma entrada de log	`boolean`
`app.agents()`	Listar todos os agentes disponíveis	`Agent[]`

Exemplos

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

Método	Descrição	Resposta
`project.list()`	Listar todos os projetos	`Project[]`

Exemplos

JavaScript

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

Método	Descrição	Resposta
`path.get()`	Obter caminho atual	`Path`

Exemplos

JavaScript

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

Método	Descrição	Resposta
`config.get()`	Obter informações de configuração	`Config`
`config.providers()`	Listar provedores e modelos padrão	`{ providers:` `Provider[], default: { [key: string]: string } }`

Exemplos

JavaScript

const config = await client.config.get()

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

Método	Descrição	Notas
`session.list()`	Listar sessões	Retorna `Session[]`
`session.get({ path })`	Obter sessão	Retorna `Session`
`session.children({ path })`	Listar sessões filhas	Retorna `Session[]`
`session.create({ body })`	Criar sessão	Retorna `Session`
`session.delete({ path })`	Deletar sessão	Retorna `boolean`
`session.update({ path, body })`	Atualizar propriedades da sessão	Retorna `Session`
`session.init({ path, body })`	Analisar app e criar `AGENTS.md`	Retorna `boolean`
`session.abort({ path })`	Abortar uma sessão em execução	Retorna `boolean`
`session.share({ path })`	Compartilhar sessão	Retorna `Session`
`session.unshare({ path })`	Descompartilhar sessão	Retorna `Session`
`session.summarize({ path, body })`	Resumir sessão	Retorna `boolean`
`session.messages({ path })`	Listar mensagens em uma sessão	Retorna `{ info:` `Message, parts:` `Part[]}[]`
`session.message({ path })`	Obter detalhes da mensagem	Retorna `{ info:` `Message, parts:` `Part[]}`
`session.prompt({ path, body })`	Enviar mensagem de prompt	`body.noReply: true` retorna UserMessage (apenas contexto). O padrão retorna `AssistantMessage` com resposta da AI. Suporta `body.outputFormat` para saída estruturada
`session.command({ path, body })`	Enviar comando para a sessão	Retorna `{ info:` `AssistantMessage, parts:` `Part[]}`
`session.shell({ path, body })`	Executar um comando shell	Retorna `AssistantMessage`
`session.revert({ path, body })`	Reverter uma mensagem	Retorna `Session`
`session.unrevert({ path })`	Restaurar mensagens revertidas	Retorna `Session`
`postSessionByIdPermissionsByPermissionId({ path, body })`	Responder a um pedido de permissão	Retorna `boolean`

Exemplos

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

Método	Descrição	Resposta
`find.text({ query })`	Pesquisar texto em arquivos	Array de objetos de correspondência com `path`, `lines`, `line_number`, `absolute_offset`, `submatches`
`find.files({ query })`	Encontrar arquivos e diretórios por nome	`string[]` (caminhos)
`find.symbols({ query })`	Encontrar símbolos no workspace	`Symbol[]`
`file.read({ query })`	Ler um arquivo	`{ type: "raw" \| "patch", content: string }`
`file.status({ query? })`	Obter status para arquivos rastreados	`File[]`

find.files suporta alguns campos de consulta opcionais:

type: "file" ou "directory"
directory: substituir a raiz do projeto para a pesquisa
limit: resultados máximos (1–200)

Exemplos

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

Método	Descrição	Resposta
`tui.appendPrompt({ body })`	Adicionar texto ao prompt	`boolean`
`tui.openHelp()`	Abrir o diálogo de ajuda	`boolean`
`tui.openSessions()`	Abrir o seletor de sessões	`boolean`
`tui.openThemes()`	Abrir o seletor de temas	`boolean`
`tui.openModels()`	Abrir o seletor de modelos	`boolean`
`tui.submitPrompt()`	Enviar o prompt atual	`boolean`
`tui.clearPrompt()`	Limpar o prompt	`boolean`
`tui.executeCommand({ body })`	Executar um comando	`boolean`
`tui.showToast({ body })`	Mostrar notificação toast	`boolean`

Exemplos

JavaScript

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

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

Método	Descrição	Resposta
`auth.set({ ... })`	Definir credenciais de autenticação	`boolean`

Exemplos

JavaScript

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

Método	Descrição	Resposta
`event.subscribe()`	Fluxo de eventos enviados pelo servidor	Fluxo de eventos enviados pelo servidor

Exemplos

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

Instalar

Criar cliente

Opções

Configuração

Apenas cliente

Opções

Tipos

Erros

Saída Estruturada

Uso Básico

Tipos de Formato de Saída

Formato do Esquema JSON

Tratamento de Erros

Melhores Práticas

APIs

Global

Exemplos

App

Exemplos

Projeto

Exemplos

Caminho

Exemplos

Configuração

Exemplos

Sessões

Exemplos

Arquivos

Exemplos

TUI

Exemplos

Autenticação

Exemplos

Eventos

Exemplos