Opencode SDK Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Opencode SDK Integration provides a multi-model routing layer within the application, allowing users to access various Large Language Model (LLM) providers through a unified interface. It acts as a pluggable alternative to the Claude Agent SDK, supporting models from OpenAI, Zhipu, xAI, and others via the Opencode platform.
Sources: README.md:144-154, server/providers/opencode-provider.js:1-10
This integration handles server-side session management, event-based streaming using Server-Sent Events (SSE), and Model Context Protocol (MCP) tool routing specifically tailored for the Opencode ecosystem.
Sources: README.md:152-156, server/providers/opencode-provider.js:105-115
Architecture Overview
The Opencode integration is implemented as a provider class that extends a base provider interface, ensuring compatibility with the existing chat routing logic in the backend.
The diagram shows the flow from the user interface through the Electron IPC bridge to the backend provider system, which eventually communicates with the Opencode SDK and external tools.
Sources: README.md:104-122, server/providers/index.js:5-10
Key Components
| Component | Description | File Path |
|---|---|---|
OpencodeProvider | Main implementation class adapting Opencode SDK to the project's provider interface. | server/providers/opencode-provider.js |
initializeProviders | Global initialization function that starts the Opencode server/client on backend startup. | server/providers/index.js |
updateOpencodeConfig | Helper function that persists MCP configurations (like Composio) to opencode.json. | server/server.js |
createOpencode | SDK method used to instantiate a local Opencode server and client. | server/providers/opencode-provider.js |
Sources: server/providers/opencode-provider.js:7-15, server/server.js:40-52, server/providers/index.js:61-70
Session and Streaming Logic
Opencode utilizes an event-driven streaming model. Unlike direct HTTP responses, the provider subscribes to an event stream and maps asynchronous events back into the application's normalized chunk format.
Streaming Sequence
The sequence illustrates how the provider handles asynchronous event updates to simulate real-time streaming for the frontend.
Sources: server/providers/opencode-provider.js:125-230
Event Handling
The query generator in OpencodeProvider monitors specific event types:
- message.part.updated: Contains incremental text, reasoning, or tool invocation data. Delta logic is applied to text parts by tracking
lastYieldedLength. - session.idle: Indicates the completion of the model's turn.
- session.error: Captures and yields error states to the frontend.
Sources: server/providers/opencode-provider.js:154-220
Configuration and Tool Integration
The integration requires a specific configuration file, server/opencode.json, which the Opencode SDK reads to discover MCP (Model Context Protocol) servers.
Automatic MCP Configuration
The backend server automatically updates the configuration on startup or when a new Composio session is created.
function updateOpencodeConfig(mcpUrl, mcpHeaders) {
const opencodeConfigPath = path.join(__dirname, 'opencode.json');
const config = {
mcp: {
composio: {
type: 'remote',
url: mcpUrl,
headers: mcpHeaders
}
}
};
fs.writeFileSync(opencodeConfigPath, JSON.stringify(config, null, 2));
}
Sources: server/server.js:40-52, README.md:195-212
Model Options
The frontend allows selection of various models through the Opencode provider, mapped in renderer.js.
| Model ID | Label | Description |
|---|---|---|
opencode/big-pickle | Big Pickle | Default reasoning model |
opencode/gpt-5-nano | GPT-5 Nano | OpenAI reasoning capability |
opencode/grok-code | Grok Code Fast | xAI coding-optimized model |
anthropic/claude-sonnet... | Claude Sonnet | Anthropic models via Opencode route |
Sources: renderer/renderer.js:52-62
Implementation Details
Provider Initialization
During initialization, the provider can either start a new local Opencode server (defaulting to port 4096) or connect to an existing one via a base URL.
async initialize() {
if (this.client) return;
const { client, server } = await createOpencode({
hostname: this.hostname,
port: this.port
});
this.client = client;
this.serverInstance = server;
}
Sources: server/providers/opencode-provider.js:47-65
Normalization
The normalizeChunk method ensures that Opencode-specific part types (like reasoning or tool-invocation) are converted into the standard format expected by the renderer.js streaming handler. This includes handling tool_use and tool_result identifiers across different SDK naming conventions.
Sources: server/providers/opencode-provider.js:246-280, renderer/renderer.js:770-810
Conclusion
The Opencode SDK Integration expands the application's capabilities beyond the Anthropic ecosystem by providing a standardized bridge to multiple LLM providers. By combining a local server instance with an event-driven provider architecture and automated MCP configuration, it enables complex tool-use and reasoning capabilities across a wide array of models while maintaining a consistent user experience.
Sources: README.md:144-160, server/providers/opencode-provider.js:7-15