Express Server Setup

Relevant source files

The following files were used as context for generating this wiki page:

• server/server.js
• server/package.json
• server/providers/claude-provider.js
• server/providers/opencode-provider.js
• preload.js
• README.md

The Express server serves as the backbone of the Open Claude Cowork application, acting as the intermediary between the Electron frontend and various AI provider SDKs. Its primary purpose is to handle chat requests, manage AI sessions via a pluggable provider system, and integrate external tools through the Composio Tool Router and Model Context Protocol (MCP).

The server is built using Node.js and Express, utilizing Server-Sent Events (SSE) to stream real-time, token-by-token responses back to the client. It handles the orchestration of multiple LLM providers (Claude and Opencode) and ensures that tool calls from 500+ external apps are properly routed and visualised.

Sources: server/server.js:1-15, README.md:83-100

Server Architecture and Lifecycle

The server initialization involves setting up environment variables, initializing AI providers, and establishing a default Composio session for MCP tool integration.

Startup Sequence

When the server starts, it executes several critical asynchronous tasks:

1. Environment Configuration: Loads variables from .env using dotenv.
2. Provider Initialization: Calls initializeProviders() to set up available AI SDKs.
3. Composio Session: Creates a default session for the 'default-user' and updates the opencode.json configuration file with the generated MCP URL and headers.

The diagram above illustrates the sequential steps the backend takes during the startup phase to ensure all integrations are ready for client requests.

Sources: server/server.js:12-42, server/server.js:174-177

API Endpoints

The server exposes a RESTful API to manage chats, retrieve provider information, and check system health.

Core Endpoints

Endpoint	Method	Description
/api/chat	POST	Main chat entry point. Establishes an SSE stream for AI responses.
/api/abort	POST	Cancels an ongoing query/stream for a specific chatId.
/api/providers	GET	Returns a list of available AI providers (e.g., 'claude', 'opencode').
/api/health	GET	Simple health check returning status and current timestamp.

Sources: server/server.js:52, server/server.js:139, server/server.js:161, server/server.js:169

Chat Request Processing

The /api/chat endpoint accepts a JSON body containing the user message, chatId, provider, and model. It validates the provider and initializes a user-specific Composio session if one does not already exist.

This sequence shows the flow of a single chat request, emphasizing the transition to an asynchronous event stream.

Sources: server/server.js:52-120, preload.js:46-85

AI Provider Integration

The server uses a pluggable architecture to support different LLM backends through a unified interface.

Claude Provider

Utilizes the @anthropic-ai/claude-agent-sdk. It supports session resumption using a session_id and enables "Skills" by loading markdown instructions from the filesystem (user and project sources).

• Default Tools: Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, TodoWrite, Skill.
• Session Management: Captures session_id from system init messages to maintain context.

Sources: server/providers/claude-provider.js:1-60, README.md:156-166

Opencode Provider

Utilizes the @opencode-ai/sdk to route requests to various models like big-pickle, gpt-5-nano, and grok-code.

• Event-based Streaming: Listens for message.part.updated events.
• Reasoning Support: Explicitly handles reasoning parts for models with extended thinking capabilities.
• MCP Handling: While Claude receives MCP configs via API, Opencode primarily reads its tool configuration from server/opencode.json.

Sources: server/providers/opencode-provider.js:1-120, README.md:167-185

Configuration and Middleware

The server is configured with several key dependencies and settings as defined in the package manifest.

Dependencies

{
  "dependencies": {
    "express": "^5.2.1",
    "@anthropic-ai/claude-agent-sdk": "^0.2.7",
    "@composio/core": "latest",
    "@opencode-ai/sdk": "latest",
    "dotenv": "^16.4.5",
    "cors": "^2.8.5"
  }
}

Sources: server/package.json:11-18

Middleware Stack

1. CORS: Enabled via cors() to allow requests from the Electron frontend.
2. JSON Parser: express.json() handles incoming request bodies.
3. SSE Headers: The /api/chat endpoint manually sets headers to ensure real-time delivery:
   • Content-Type: text/event-stream
   • Cache-Control: no-cache, no-transform
   • X-Accel-Buffering: no (to prevent proxy buffering)

Sources: server/server.js:47-49, server/server.js:73-77

Summary

The Express server setup in Open Claude Cowork provides a robust, streaming backend that abstracts the complexities of multi-provider AI interactions. By managing sessions, coordinating with the Composio tool router, and exposing a consistent SSE-based API, it enables the native desktop application to perform complex, multi-turn agentic tasks with real-time feedback.