Provider Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Provider Architecture in Open Claude Cowork is a pluggable system designed to abstract different AI model backends. It allows the application to switch between various Large Language Model (LLM) implementations—such as the Claude Agent SDK and Opencode—while maintaining a consistent interface for the frontend.
This architecture centralizes session management, tool execution, and real-time streaming logic. By utilizing a base provider interface, the system ensures that any new AI service can be integrated by implementing a standard set of methods for querying and resource management.
Sources: README.md, server/providers/base-provider.js:1-6, server/providers/index.js:4-8
Core Components
The architecture consists of a registry, a base interface, and specific implementations.
Provider Registry and Factory
The system uses a centralized registry to manage available providers. The getProvider function serves as a factory, ensuring that provider instances are cached and reused based on their configuration.
| Component | Responsibility |
|---|---|
providers | An object mapping provider names (e.g., 'claude', 'opencode') to their respective classes. |
getProvider() | Retrieves or creates a cached instance of a provider. |
initializeProviders() | Triggers initialization logic for specific providers (e.g., Opencode) during server startup. |
Sources: server/providers/index.js:4-19, server/providers/index.js:56-66
Base Provider Interface
All AI service integrations must extend the BaseProvider class. This abstract class defines the contract for session handling and query execution.
The diagram above illustrates the inheritance structure of the provider system.
Sources: server/providers/base-provider.js:5-84, server/providers/claude-provider.js:8-13
Query and Streaming Flow
The communication between the frontend and a provider follows a structured request-response cycle using Server-Sent Events (SSE) for real-time interaction.
Request Pipeline
- Frontend Request: The
renderer.jssends a message with a selectedproviderandmodel. - Preload Bridge:
preload.jsforwards the request to the/api/chatendpoint on the Express server. - Server Dispatch:
server.jsidentifies the correct provider using the registry and calls itsquerymethod. - SDK Execution: The provider implementation (e.g.,
ClaudeProvider) interacts with the underlying AI SDK.
The sequence diagram shows the flow of a chat request from the UI through the provider abstraction layer.
Sources: renderer/renderer.js:636-645, server/server.js:68-85, server/server.js:118-140, preload.js:37-60
Response Normalization
Each provider is responsible for yielding normalized chunks so the frontend does not need to handle SDK-specific formats. Supported chunk types include:
text: Standard text output from the model.tool_use: Instructions to execute a specific tool (e.g.,Bash,WebSearch).tool_result: The output or outcome of a tool execution.session_init: Metadata regarding the established session ID.
Sources: server/providers/claude-provider.js:106-135, server/server.js:142-155
Session and Tool Management
Providers handle both the lifecycle of the AI conversation and the integration of external tools via the Composio Tool Router.
Session Persistence
Providers maintain a mapping of chatId (frontend-generated) to sessionId (SDK-generated). This allows users to resume conversations across application restarts.
- Claude: Uses the
resumeoption in the Claude Agent SDK with a capturedsession_id. - Opencode: Maintains session state per chat conversation.
Sources: README.md: "Session Management", server/providers/claude-provider.js:84-90, server/providers/base-provider.js:47-62
Tool Configuration
The architecture passes a standardized set of tools and MCP (Model Context Protocol) server configurations to the provider's query method.
| Parameter | Description |
|---|---|
mcpServers | Configuration for Composio, providing access to 500+ tools. |
allowedTools | A list of permitted capabilities including Bash, Grep, WebFetch, and Skill. |
settingSources | Filesystem locations (user/project) for loading Agent Skills. |
Sources: server/server.js:125-132, server/providers/claude-provider.js:70-76
Abort Functionality
Both the client and server support interrupting long-running queries.
- The
ClaudeProvidermaintains aMapofAbortControllers. - When a user clicks "Stop" or switches chats, an API call to
/api/aborttriggers the controller for that specificchatId.
Sources: server/providers/claude-provider.js:25-34, server/server.js:176-193, preload.js:24-34
Summary
The Provider Architecture provides a robust foundation for multi-LLM support in Open Claude Cowork. By isolating SDK complexities within individual provider implementations and exposing a unified query interface, the system ensures scalability and simplifies the integration of specialized agentic capabilities like tool use and persistent sessions.
Sources: server/providers/index.js:1-66, server/server.js:62-174