opencode-sdk

Rust SDK for OpenCode HTTP API with SSE streaming support. Provides ergonomic async client, 15 REST API modules, 40+ event types, and managed server lifecycle.

Use this file to understand the SDK structure, feature flags, and correct API usage patterns. All examples assume async context with tokio runtime.

Agent Operating Rules

1. Always check feature flags before using APIs - http and sse are enabled by default, server and cli require explicit enabling.
2. Unix platforms only - Windows will fail at compile time with compile_error!.
3. Subscribe before sending - For streaming workflows, create SSE subscription before sending async prompts to avoid missing early events.
4. Use convenience methods - Prefer Client::run_simple_text() and wait_for_idle_text() for common workflows.
5. Handle all error variants - Match on OpencodeError variants, using helper methods like is_not_found() and is_validation_error().
6. Drop subscriptions to cancel - SseSubscription and RawSseSubscription cancel on drop; explicitly call .close() for early termination.
7. Server processes auto-kill - ManagedServer kills child process on drop; call .stop() for graceful shutdown.
8. Directory header required - Most operations require x-opencode-directory header set via ClientBuilder::directory() or ManagedRuntimeBuilder::directory().
9. URL encode path parameters - All path parameters must be URL-encoded using urlencoding::encode() to handle special characters.

Environment and Version Constraints