Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

opencode.md

186 lines9.7 KB

1---
2title: OpenCode
3id: opencode-adapter
4order: 14
5description: "Use OpenCode as a chat backend in TanStack AI — agent harness with local tool execution, token-level streaming, stateful sessions, and tool bridging via @tanstack/ai-opencode."
6keywords:
7 - tanstack ai
8 - opencode
9 - opencode sdk
10 - harness
11 - agent
12 - coding agent
13 - adapter
14---
15​
16The OpenCode adapter runs [OpenCode](https://opencode.ai) as a chat backend, driving it over its local HTTP server (`@opencode-ai/sdk`). Unlike HTTP provider adapters, this is a **harness adapter**: OpenCode runs its own agent loop and executes its own tools — shell commands, file reads and edits, search — locally on your server. Each `chat()` call runs one full harness turn; assistant text and reasoning stream as true token-level deltas, and the harness's tool activity streams back as already-resolved tool-call events your UI can render.
17​
18> **Server-only.** The adapter spawns (or attaches to) an `opencode serve` process, so it only works in a Node.js server environment — never in the browser. Treat it like giving OpenCode a shell on the machine it runs on, and configure permissions accordingly.
19​
20## Installation
21​
22```bash
23npm install @tanstack/ai-opencode
24```
25​
26The `opencode` CLI must be installed and its providers authenticated on the host:
27​
28```bash
29npm install -g opencode-ai
30opencode auth login
31```
32​
33A runnable demo lives at [`examples/sandbox-cloudflare`](https://github.com/TanStack/ai/tree/main/examples/sandbox-cloudflare) — pick Claude Code, Codex, or Grok Build in the UI, with session resume, the harness tool timeline, and tool bridging, wired into a TanStack Start app on Workers. For the same wiring on plain Node with durable, refresh-surviving runs (Claude Code on Docker), see [`examples/sandbox-web`](https://github.com/TanStack/ai/tree/main/examples/sandbox-web) — swapping in this adapter is a one-line change (`src/sandbox-agent.ts`).
34​
35## Models
36​
37OpenCode is provider-agnostic: it resolves any `provider/model` id its configured providers support. Address models as `provider/model` (the adapter splits on the first `/`):
38​
39```typescript
40import { chat } from "@tanstack/ai";
41import { opencodeText } from "@tanstack/ai-opencode";
42​
43const stream = chat({
44 adapter: opencodeText("anthropic/claude-sonnet-4-5", {
45 directory: "/path/to/project",
46 permissionMode: "acceptEdits",
47 }),
48 messages: [{ role: "user", content: "Fix the failing test in utils.test.ts" }],
49});
50```
51​
52## Configuration
53​
54| Option | Description |
55| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
56| `directory` | Working directory for the harness session. Defaults to `process.cwd()`. |
57| `baseUrl` | Attach to an already-running `opencode serve` (e.g. `http://127.0.0.1:4096`) instead of spawning a new server per turn. |
58| `hostname` | Hostname for the spawned server. Defaults to the SDK default (`127.0.0.1`). |
59| `port` | Port for the spawned server. Defaults to the SDK default (`4096`). |
60| `permissionMode` | `'default'` (bridged tools run, everything else that prompts is rejected), `'acceptEdits'` (also auto-approves file edits), or `'bypassPermissions'` (allow all). |
61| `onPermissionRequest` | Custom permission handler; replaces the default policy entirely. |
62| `config` | Extra OpenCode config merged with the adapter's MCP and permission config. |
63​
64Per-call overrides — `sessionId`, `permissionMode`, `directory` — go through `modelOptions`.
65​
66## Permissions
67​
68OpenCode asks for permission before mutating files or running commands. A headless server has no one to answer those prompts, so the adapter applies a policy automatically — it never hangs a turn:
69​
70- **`'default'`** — bridged TanStack tools run; anything else that would prompt (edits, shell, web fetch) is rejected.
71- **`'acceptEdits'`** — additionally auto-approves file-mutation requests (edit / write / patch).
72- **`'bypassPermissions'`** — approves everything. Only use this against a sandbox or scratch directory.
73​
74Provide `onPermissionRequest` to implement your own policy (e.g. allow-list specific commands).
75​
76## Stateful Sessions
77​
78OpenCode sessions are stateful — the harness keeps the full working context (files read, commands run, conclusions reached) between turns. The adapter surfaces the session id of every fresh run as a custom stream event named `opencode.session-id`; thread it back via `modelOptions.sessionId` to resume. When resuming, only the latest user message is sent — the harness already holds the prior context.
79​
80Server endpoint:
81​
82```typescript
83import {
84 chat,
85 chatParamsFromRequest,
86 toServerSentEventsResponse,
87} from "@tanstack/ai";
88import { opencodeText } from "@tanstack/ai-opencode";
89​
90export async function POST(request: Request) {
91 const params = await chatParamsFromRequest(request);
92​
93 // Extra fields the client puts in the connection `body` arrive here.
94 const sessionId =
95 typeof params.forwardedProps.sessionId === "string"
96 ? params.forwardedProps.sessionId
97 : undefined;
98​
99 const stream = chat({
100 adapter: opencodeText("anthropic/claude-sonnet-4-5", {
101 directory: "/path/to/project",
102 permissionMode: "acceptEdits",
103 }),
104 messages: params.messages,
105 modelOptions: { sessionId },
106 });
107​
108 return toServerSentEventsResponse(stream);
110```
111​
112Client (React) — capture the session id from the custom event and send it back on subsequent requests:
113​
114```typescript
115import { useState } from "react";
116import { useChat } from "@tanstack/ai-react";
117import { fetchServerSentEvents } from "@tanstack/ai-client";
118​
119function CodingAssistant() {
120 const [sessionId, setSessionId] = useState<string | undefined>(undefined);
121​
122 const { messages, sendMessage } = useChat({
123 connection: fetchServerSentEvents("/api/chat", () => ({
124 body: { sessionId },
125 })),
126 onCustomEvent: (name, value) => {
127 if (
128 name === "opencode.session-id" &&
129 typeof value === "object" &&
130 value !== null &&
131 "sessionId" in value &&
132 typeof value.sessionId === "string"
133 ) {
134 setSessionId(value.sessionId);
135 }
136 },
137 });
138​
139 // ... render messages; harness tool activity (bash, edit, read, ...)
140 // arrives as regular tool-call parts with results.
142```
143​
144Sessions live on the server that ran them, so resuming only works against the same server instance (or a shared `baseUrl`).
145​
146## Tools
147​
148Two kinds of tools flow through this adapter:
149​
1501. **Built-in harness tools** are executed by OpenCode itself and stream back as tool-call events with results already attached: `bash`, `edit`, `write`, `read`, `grep`, and the agent's running todo plan (surfaced as an `opencode.todo` custom event). Your code never executes them.
151​
1522. **Your TanStack tools** are bridged *into* the harness: the adapter starts a short-lived Streamable-HTTP MCP server on `127.0.0.1` for the duration of the turn and registers it with OpenCode. Define tools as usual with `toolDefinition().server()`; tool-call events come back under the names you registered (OpenCode prefixes MCP tools `tanstack_…` internally, which the adapter strips).
153​
154```typescript
155import { z } from "zod";
156import { chat, toolDefinition } from "@tanstack/ai";
157import { opencodeText } from "@tanstack/ai-opencode";
158​
159const lookupTicket = toolDefinition({
160 name: "lookup_ticket",
161 description: "Look up an issue ticket by id",
162 inputSchema: z.object({ ticketId: z.string() }),
163}).server(async ({ ticketId }) => {
164 return { ticketId, status: "open", title: "Crash on startup" };
165});
166​
167const stream = chat({
168 adapter: opencodeText("anthropic/claude-sonnet-4-5"),
169 messages: [{ role: "user", content: "What's the status of ticket T-123?" }],
170 tools: [lookupTicket],
171});
172```
173​
174**Client-side and approval-gated tools are not supported.** The harness executes tools inside a live process, which cannot pause across HTTP requests to wait for a browser round-trip or a human approval. Passing a tool without a server `execute()` implementation — or one marked `needsApproval` — fails fast with a descriptive error. Run those tools outside the harness with a regular provider adapter.
175​
176## Structured Output
177​
178`structuredOutput()` is best-effort: OpenCode's prompt API has no native JSON-schema channel, so the schema is embedded as a prompt instruction in a fresh, one-shot session and the final text is parsed (markdown fences are stripped when present). It works for finalization after a chat, but a plain provider adapter (e.g. `@tanstack/ai-openai`) is the better choice when structured extraction is the primary job — it's faster, deterministic, and doesn't spawn a harness.
179​
180## Limitations
181​
182- **Server-only (Node).** The adapter spawns or attaches to an `opencode serve` process.
183- **The harness owns the agent loop.** TanStack's agent-loop strategies and per-iteration middleware don't apply inside a harness turn.
184- **No sampling controls.** `temperature`-style options don't exist here.
185- **Sessions are server-local.** Resume requires hitting the same server instance (or a shared `baseUrl`).
186- **Cold starts.** Spawning a server per turn adds first-token latency; point the adapter at a long-lived `baseUrl` to avoid it.