mirror of
https://github.com/anomalyco/opencode.git
synced 2026-07-13 13:28:27 +00:00
91 lines
2.5 KiB
Text
91 lines
2.5 KiB
Text
---
|
|
title: "Client"
|
|
description: "Connect an application to the OpenCode HTTP API."
|
|
---
|
|
|
|
`@opencode-ai/client` is the generated TypeScript client for the OpenCode HTTP
|
|
API. Use it when your application connects to an OpenCode server over the
|
|
network. Its types and methods are generated from the same contract as the
|
|
[API reference](/api).
|
|
|
|
<Warning>
|
|
The V2 API and client are beta. Method names, inputs, and outputs may change
|
|
before the stable release.
|
|
</Warning>
|
|
|
|
## Install
|
|
|
|
```sh
|
|
bun add @opencode-ai/client
|
|
```
|
|
|
|
The package has two entrypoints:
|
|
|
|
- `@opencode-ai/client/promise` uses `fetch` and returns Promises or async
|
|
iterables. It has no Effect runtime dependency.
|
|
- `@opencode-ai/client/effect` returns Effects and Streams, decodes values into
|
|
the V2 schema types, and requires an `HttpClient` service from Effect.
|
|
|
|
## Promise client
|
|
|
|
Create a client with the server URL, then call methods grouped by API resource:
|
|
|
|
```ts
|
|
import { OpenCode } from "@opencode-ai/client/promise"
|
|
|
|
const client = OpenCode.make({
|
|
baseUrl: "http://localhost:4096",
|
|
})
|
|
|
|
const session = await client.session.create({
|
|
location: { directory: "/workspace" },
|
|
})
|
|
|
|
await client.session.prompt({
|
|
sessionID: session.id,
|
|
text: "Review the current changes",
|
|
})
|
|
```
|
|
|
|
Pass default authentication or application headers to `OpenCode.make` with
|
|
`headers`. You can also supply a custom `fetch` implementation. Each operation
|
|
accepts request options as its final argument for an `AbortSignal` or
|
|
per-request headers.
|
|
|
|
Streaming endpoints return async iterables:
|
|
|
|
```ts
|
|
for await (const event of client.event.subscribe()) {
|
|
console.log(event.type)
|
|
}
|
|
```
|
|
|
|
## Effect client
|
|
|
|
Install the `effect` peer dependency when using the Effect entrypoint. The
|
|
client uses canonical V2 values such as `Location.Ref` and `Session.ID`, and
|
|
returns typed failures in the Effect error channel.
|
|
|
|
```ts
|
|
import { AbsolutePath, Location, OpenCode } from "@opencode-ai/client/effect"
|
|
import { Effect } from "effect"
|
|
import { FetchHttpClient } from "effect/unstable/http"
|
|
|
|
const program = Effect.gen(function* () {
|
|
const client = yield* OpenCode.make({ baseUrl: "http://localhost:4096" })
|
|
const session = yield* client.session.create({
|
|
location: Location.Ref.make({
|
|
directory: AbsolutePath.make("/workspace"),
|
|
}),
|
|
})
|
|
|
|
return yield* client.session.get({ sessionID: session.id })
|
|
})
|
|
|
|
const session = await Effect.runPromise(
|
|
program.pipe(Effect.provide(FetchHttpClient.layer)),
|
|
)
|
|
```
|
|
|
|
Streaming operations, including `client.event.subscribe()` and
|
|
`client.session.log(...)`, return Effect `Stream` values.
|