Claude Agent SDK Integration

Relevant source files

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

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

The Claude Agent SDK Integration provides the core agentic capabilities for the Open Claude Cowork application. It leverages Anthropic's SDK to enable multi-turn conversations, autonomous tool use, and sophisticated session management. This integration allows the application to function not just as a chatbot, but as an agent capable of executing complex workflows by interacting with external tools and local filesystems.

The architecture is built on a provider pattern where the ClaudeProvider class encapsulates the SDK logic, handling request orchestration, streaming response normalization, and session persistence. It integrates deeply with the Composio Tool Router to provide access to hundreds of third-party applications and local system tools like Bash and filesystem operations.

Sources: README.md:143-155, server/providers/claude-provider.js:7-15

Architecture and Data Flow

The integration follows a tiered architecture involving the Electron Frontend, an Express Backend, and the Claude Agent SDK. The backend acts as a proxy that manages sessions and streams events from the SDK to the frontend using Server-Sent Events (SSE).

Request Orchestration Flow

The following diagram illustrates the flow of a message from the user interface through the backend to the Claude Agent SDK and back.

The data flow begins in renderer.js when a user submits a prompt. The preload.js bridge facilitates an HTTP POST request to the backend. The backend identifies the requested provider and invokes the query method of the ClaudeProvider.

Sources: renderer/renderer.js:569-600, preload.js:33-55, server/server.js:63-85, server/providers/claude-provider.js:52-80

ClaudeProvider Implementation

The ClaudeProvider class is the primary interface for SDK interactions. It manages default configurations, active request lifecycles, and session state.

Key Configuration and Properties

Property	Description	Default Value
defaultAllowedTools	Array of tools the agent is permitted to use	['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep', 'WebSearch', 'WebFetch', 'TodoWrite', 'Skill']
defaultMaxTurns	Maximum number of agentic steps per query	20
permissionMode	Handling of tool execution permissions	'bypassPermissions'
settingSources	Locations for loading Agent Skills	['user', 'project']

Sources: server/providers/claude-provider.js:12-20, server/providers/claude-provider.js:63-67

Query Execution and Streaming

The query method is an asynchronous generator that streams normalized chunks. It handles:

1. Session Resumption: Checks for an existing session_id mapped to the chatId to maintain context.
2. Abort Management: Maps an AbortController to the chatId to allow mid-stream cancellation.
3. Chunk Normalization: Converts raw SDK events into a unified format for the frontend (types: text, tool_use, tool_result, session_init, done).

Sources: server/providers/claude-provider.js:52-158, server/server.js:127-145

Session Management

The integration uses the Claude Agent SDK's built-in session persistence. Sessions are tracked server-side and resumed based on client-provided chat identifiers.

When a new session starts, the SDK emits a system message with a subtype: 'init'. The ClaudeProvider captures this session_id and stores it in a Map. Subsequent requests for the same chatId include the resume option in the SDK configuration.

Sources: server/providers/claude-provider.js:82-96, server/providers/claude-provider.js:108-120, README.md:157-162

Tool Integration and Agent Skills

The Claude Agent SDK integration supports two primary ways to extend functionality: Tool Use and Agent Skills.

Tool Call Lifecycle

1. Request: The SDK yields an assistant message containing a tool_use block.
2. Display: The frontend renders an "Inline Tool Call" showing the tool name and input parameters.
3. Execution: The SDK executes the tool (via Composio or local execution).
4. Result: The SDK yields a tool_result chunk, which the frontend uses to update the UI.

Sources: server/providers/claude-provider.js:125-148, renderer/renderer.js:1042-1070

Agent Skills

Skills are specialized capabilities defined as markdown files in .claude/skills/. The integration enables these by configuring settingSources to include user and project directories and adding Skill to the allowedTools list.

// server/providers/claude-provider.js:63-67
const queryOptions = {
  allowedTools,
  maxTurns,
  mcpServers,
  permissionMode: this.permissionMode,
  settingSources: ['user', 'project']  // Enable Skills from filesystem
};

Sources: server/providers/claude-provider.js:63-67, README.md:189-210

Request Interruption (Abort)

The system supports explicit query cancellation. When a user clicks the "Stop" button in the UI, an abort signal is sent through the stack.

• Frontend: renderer.js calls window.electronAPI.stopQuery().
• Preload: Sends a POST request to /api/abort.
• Backend: server.js calls provider.abort(chatId).
• Provider: Invokes abort() on the AbortController stored in the abortControllers Map, which triggers the abortSignal passed to the SDK's query function.

Sources: renderer/renderer.js:527-548, preload.js:17-31, server/server.js:160-184, server/providers/claude-provider.js:28-38

Summary

The Claude Agent SDK integration is the engine of the Open Claude Cowork app, providing a robust bridge between Anthropic's generative models and actionable system tools. By combining streaming SSE, persistent session management, and a pluggable tool/skill architecture, it creates a seamless agentic experience. The implementation ensures technical reliability through dedicated abort handling and standardized chunk normalization across the backend-to-frontend boundary.