High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Open Claude Cowork application is an open-source desktop chat interface designed to facilitate end-to-end task automation through the Claude Agent SDK and Opencode SDK. It utilizes a decoupled architecture consisting of an Electron-based frontend and a Node.js/Express backend. This separation allows for robust session management, real-time response streaming via Server-Sent Events (SSE), and seamless integration with external tools via the Composio Tool Router.
Sources: README.md:1-25, README.md:120-145
System Overview
The application follows a classic Electron multi-process pattern. The Main Process manages native window lifecycle and system events, while the Renderer Process handles the User Interface (UI). Communication between these layers is secured through a Preload script acting as an IPC (Inter-Process Communication) bridge. The Renderer communicates with the standalone Backend Server via HTTP and SSE for AI processing and tool execution.
Architectural Diagram
The following diagram illustrates the high-level components and their communication protocols:
Sources: README.md:120-145, main.js, preload.js, server/server.js
Core Components
1. Frontend (Renderer Process)
The frontend is built with vanilla JavaScript, CSS, and HTML. It is responsible for rendering the chat interface, managing local chat history in localStorage, and handling the complex logic of streaming markdown and tool calls.
- State Management: Tracks current chat IDs, todos, tool calls, and selected AI providers.
- Streaming Handler: Uses the
ReadableStreamAPI to process incoming SSE chunks from the backend. - UI Views: Manages transitions between the "Home View" (initial prompt) and "Chat View" (ongoing conversation).
Sources: renderer/renderer.js:33-110, renderer/index.html
2. Backend Server
The backend is an Express.js application that serves as an intermediary between the Electron app and AI SDKs.
- Provider System: Abstraction layer allowing the app to switch between the Claude Agent SDK and Opencode SDK.
- Session Management: Maintains conversation context server-side. For the Claude provider, it utilizes the SDK's built-in session tracking.
- MCP Configuration: Automatically generates and updates
server/opencode.jsonwith Composio MCP (Model Context Protocol) credentials to enable tool access.
Sources: server/server.js:30-70, README.md:148-160
3. Tool Integration (Composio & MCP)
The application leverages the Model Context Protocol (MCP) to connect LLMs to over 500 external tools.
| Component | Responsibility |
|---|---|
| Composio SDK | Manages user sessions and provides the remote MCP URL. |
| Tool Router | Routes AI tool calls to specific Work Apps (Gmail, GitHub, etc.). |
| Skill System | Loads specialized capabilities from .claude/skills/ as markdown instructions. |
Sources: README.md:197-230, server/server.js:35-55
Data Flow: Chat and Tool Execution
When a user sends a message, the system follows a synchronous-request/asynchronous-response flow. The backend maintains a heartbeat connection to prevent timeout during long-running agentic tasks.
Chat Sequence Diagram
Key API Endpoints
The backend exposes several critical endpoints used by the preload.js bridge:
| Endpoint | Method | Description |
|---|---|---|
/api/chat | POST | Main entry point for messages. Returns an SSE stream. |
/api/abort | POST | Cancels an ongoing query/agent task for a specific chatId. |
/api/providers | GET | Returns a list of available AI providers configured in the environment. |
/api/health | GET | System status and provider initialization check. |
Sources: server/server.js:75-215, preload.js:15-100
Session and State Management
| Level | Mechanism | Implementation Detail |
|---|---|---|
| Frontend | localStorage | Stores allChats array containing message history, tool results, and metadata. |
| Backend | Provider Sessions | Maps chatId to SDK-specific session objects (e.g., Claude Session IDs). |
| Integrations | Composio Sessions | Maps userId to remote MCP router instances. |
Sources: renderer/renderer.js:115-170, server/server.js:30-45
The High-Level Architecture of Open Claude Cowork ensures that complex, multi-turn AI interactions remain responsive through its event-driven streaming model, while providing a extensible foundation for adding new AI providers and automated tools.