Claude Code Integration
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Claude Code Integration is the core mechanism within Agent Cowork that bridges a native desktop interface with the @anthropic-ai/claude-agent-sdk. Its primary purpose is to provide a visual, managed environment for the Claude terminal-based agent, enabling features like session persistence, real-time streaming output, and interactive permission management. By wrapping the Claude Code CLI, the system allows users to execute complex programming and file management tasks using natural language while maintaining full compatibility with existing Claude Code configurations.
Sources: README.md:14-25, README.md:41-50, src/electron/libs/runner.ts:40-60
Architecture and Core Components
The integration follows a layered architecture where the Electron main process manages the lifecycle of the Claude agent via the SDK, and the React frontend provides the user interface.
System Flow
The following diagram illustrates the flow from a user prompt to the Claude SDK execution and back to the UI.
This diagram shows the interaction between the UI, the Electron background logic, and the external Claude SDK.
Sources: src/electron/libs/runner.ts:40-100, src/electron/libs/claude-settings.ts:8-20, package.json:34-40
Key Components
| Component | Responsibility | Relevant Files |
|---|---|---|
| Runner | Manages the query lifecycle, handles SDK message streams, and processes tool permissions. | src/electron/libs/runner.ts |
| Claude Settings | Locates the Claude CLI path and retrieves API configurations from UI or ~/.claude/settings.json. | src/electron/libs/claude-settings.ts |
| Session Store | Persists session metadata and message history using a SQLite database. | src/electron/libs/session-store.ts |
| Util | Provides environment enhancement and session title generation using the SDK. | src/electron/libs/util.ts |
Sources: src/electron/libs/runner.ts:1-20, src/electron/libs/claude-settings.ts:1-10, src/electron/libs/session-store.ts:1-30
Configuration and Environment
The integration is designed to be "zero-config" by re-using existing Claude Code settings while also allowing UI-based overrides.
API Configuration Retrieval
The system attempts to resolve API settings in a prioritized order:
- UI Configuration: Custom settings saved via the application's settings modal.
- File Configuration: Fallback to the standard Claude CLI configuration located at
~/.claude/settings.json.
Sources: src/electron/libs/claude-settings.ts:23-63
Environment Variables
To ensure the SDK functions correctly within a packaged Electron environment, the system builds an enhanced environment object containing:
ANTHROPIC_AUTH_TOKEN: The API key.ANTHROPIC_BASE_URL: The API endpoint.ANTHROPIC_MODEL: The target Claude model.- Path resolution for the Claude Code executable located within
asar.unpacked.
Sources: src/electron/libs/claude-settings.ts:8-20, src/electron/libs/claude-settings.ts:80-88, src/electron/libs/util.ts:7-22
Execution Logic (The Runner)
The runClaude function is the entry point for starting an AI session. It initializes an AbortController and invokes the SDK's query method.
Session Lifecycle Sequence
The sequence below details how a query is processed and how permissions are handled asynchronously.
This sequence shows the bidirectional communication required for tool execution and real-time UI updates.
Sources: src/electron/libs/runner.ts:40-145, src/electron/types.ts:25-50
Interaction and Permissions
While most tools are auto-approved via the bypassPermissions and allowDangerouslySkipPermissions flags in the runner, the AskUserQuestion tool is explicitly intercepted. This triggers a permission.request event to the frontend, where the user must provide input before the AI can continue.
Sources: src/electron/libs/runner.ts:80-115
Data Persistence
All interactions are stored locally to allow for session resumption and history viewing.
Session and Message Schema
- Sessions: Stores
id,title,status,cwd, and the SDK'sclaude_session_id. - Messages: Stores serialized
StreamMessageobjects linked bysession_id.
Sources: src/electron/libs/session-store.ts:162-185
Resuming Sessions
The integration supports resuming existing Claude sessions by passing the resumeSessionId (the claude_session_id from the SDK) to the query options. This allows the agent to maintain context across application restarts.
Sources: src/electron/libs/runner.ts:71, src/electron/libs/session-store.ts:14-25
Conclusion
The Claude Code Integration transforms the terminal-based Claude agent into a robust desktop application feature. By managing environment variables, persisting session history in SQLite, and providing an asynchronous IPC bridge for the SDK's streaming events, the system offers a more accessible and visual way to collaborate with Anthropic's coding agent while remaining fully compatible with the official CLI's configuration.