# Opencode Sdk

> [WHAT] TypeScript SDK for programmatic control of OpenCode AI coding agent. [HOW] Client/server architecture: start embedded server or connect to existing instance. [WHEN] Use when automating OpenCode, building integrations, or controlling sessions programmatically. [WHY] Enables headless coding agent workflows, CI/CD integration, and custom tooling. Triggers: "opencode", "opencode sdk", "opencode api", "opencode programmatic", "control opencode", "opencode automation", "opencode typescript", "opencode client", "opencode server", "coding agent sdk" Category: EXECUTE (run agents) + GET (session data)

- Skill: `lev-os/opencode-sdk` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add lev-os/opencode-sdk`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lev-os/opencode-sdk/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: lev-os (https://skillmd.com/u/lev-os)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/lev-os/opencode-sdk

---


# OpenCode SDK

TypeScript SDK for the OpenCode AI coding agent. Control sessions, send prompts, and subscribe to events programmatically.

## Quick Start

```bash
npm install @opencode-ai/sdk
```

### Full Instance (Server + Client)

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

const { client, server } = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  timeout: 5000,
  config: {
    model: "anthropic/claude-sonnet-4-20250514"
  }
})

// Use client...
server.close()
```

### Client Only (Connect to Running Instance)

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

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

## Core APIs

### Sessions

```typescript
// Create session
const session = await client.session.create({
  body: { title: "My Task" }
})

// Send prompt
const result = await client.session.prompt({
  path: { id: session.id },
  body: {
    model: { providerID: "anthropic", modelID: "claude-sonnet-4-20250514" },
    parts: [{ type: "text", text: "Implement a function to..." }]
  }
})

// Inject context without AI response
await client.session.prompt({
  path: { id: session.id },
  body: {
    noReply: true,
    parts: [{ type: "text", text: "Context: This project uses..." }]
  }
})

// List sessions
const sessions = await client.session.list()

// Get session messages
const messages = await client.session.messages({ path: { id: session.id } })
```

### Files & Search

```typescript
// Search text in files
const textResults = await client.find.text({
  query: { pattern: "function.*handler" }
})

// Find files by name
const files = await client.find.files({
  query: { query: "*.ts", type: "file", limit: 50 }
})

// Find symbols
const symbols = await client.find.symbols({
  query: { query: "handleRequest" }
})

// Read file content
const content = await client.file.read({
  query: { path: "src/index.ts" }
})
```

### Events (SSE Stream)

```typescript
const events = await client.event.subscribe()

for await (const event of events.stream) {
  switch (event.type) {
    case "message.updated":
      console.log("Message:", event.properties.info)
      break
    case "session.status":
      console.log("Status:", event.properties.status)
      break
    case "permission.updated":
      // Handle permission requests
      break
  }
}
```

### TUI Control

```typescript
// Append to prompt
await client.tui.appendPrompt({ body: { text: "Add this text" } })

// Submit prompt
await client.tui.submitPrompt()

// Show toast
await client.tui.showToast({
  body: { message: "Task complete", variant: "success" }
})

// Execute command
await client.tui.executeCommand({ body: { name: "agent_cycle" } })
```

## Key Types

```typescript
import type {
  Session,
  Message,
  UserMessage,
  AssistantMessage,
  Part,
  TextPart,
  ToolPart,
  Permission,
  SessionStatus
} from "@opencode-ai/sdk"
```

## Decision Tree

```
What do you need?
│
├─→ Start OpenCode + control it?
│   └─→ createOpencode() - starts server + returns client
│
├─→ Connect to running OpenCode?
│   └─→ createOpencodeClient({ baseUrl }) - client only
│
├─→ Send prompts programmatically?
│   └─→ client.session.prompt()
│
├─→ Inject context without response?
│   └─→ client.session.prompt({ body: { noReply: true, ... } })
│
├─→ Stream events in real-time?
│   └─→ client.event.subscribe()
│
└─→ Control TUI remotely?
    └─→ client.tui.* methods
```

## Integration Patterns

### Headless Agent Loop

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

const { client, server } = await createOpencode()
const session = await client.session.create({ body: { title: "Automated" } })

// Subscribe to events for progress
const events = await client.event.subscribe()

// Send task
await client.session.prompt({
  path: { id: session.id },
  body: {
    model: { providerID: "anthropic", modelID: "claude-sonnet-4-20250514" },
    parts: [{ type: "text", text: "Fix all TypeScript errors in src/" }]
  }
})

// Wait for completion via events
for await (const event of events.stream) {
  if (event.type === "session.idle" && event.properties.sessionID === session.id) {
    break
  }
}

server.close()
```

### Permission Handling

```typescript
for await (const event of events.stream) {
  if (event.type === "permission.updated") {
    const perm = event.properties
    // Auto-approve file reads, prompt for writes
    if (perm.type === "file_read") {
      await client.postSessionIdPermissionsPermissionId({
        path: { id: perm.sessionID, permissionId: perm.id },
        body: { response: "allow" }
      })
    }
  }
}
```

## References

- `references/api-reference.md` - Complete API documentation
- `references/types.md` - Full TypeScript type definitions
- `references/events.md` - All event types and properties

## See Also

- Official docs: https://opencode.ai/docs/sdk
- OpenCode CLI: `opencode` (TUI)
- GitHub: https://github.com/anomalyco/opencode