High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Agent Cowork is a desktop AI assistant designed to provide a graphical user interface for interacting with the @anthropic-ai/claude-agent-sdk. It bridges the gap between terminal-based AI agents and a native desktop experience by managing local file operations, tool-use permissions, and real-time session streaming through an Electron-based environment.
The system is built on a split architecture where the Electron Main process handles system-level operations, file system access, and the AI SDK integration, while the React-based Renderer process manages the user interface, session state, and visual feedback for tool execution.
Sources: README.md:21-36, package.json:44-65
Core System Components
The application follows a standard Electron multi-process model, separating UI rendering from system-level logic and AI agent management.
Component Overview
| Component | Responsibility | Key Technologies |
|---|---|---|
| Main Process | Handles IPC, file system, process lifecycle, and SDK orchestration. | Electron 39, Node.js |
| Renderer Process | UI rendering, Markdown display, and user interaction. | React 19, Tailwind CSS 4 |
| State Management | Centralized client-side state for sessions and messages. | Zustand |
| AI Integration | Executes agent logic and handles tool-use interactions. | @anthropic-ai/claude-agent-sdk |
| Persistence | Stores local session history and API configurations. | better-sqlite3, JSON |
Sources: README_ZH.md:120-130, package.json:44-55
Architectural Flow
The following diagram illustrates the high-level interaction between the user interface and the backend processes.
Main Process Logic
The Main process acts as the controller, managing the lifecycle of the BrowserWindow and routing Inter-Process Communication (IPC) between the UI and the Claude SDK.
IPC Handlers and Event Routing
The Main process initializes several handlers to manage session titles, directory selection, and API configuration.
client-event: Listens for actions like starting, stopping, or continuing sessions.generate-session-title: Uses the AI SDK to analyze user input and create descriptive titles.select-directory: Invokes native dialogs for choosing working directories.
Sources: src/electron/main.ts:84-123, src/electron/libs/util.ts:25-50
Configuration Management
The system utilizes a dual-configuration approach. It attempts to load settings from a local UI-managed file (api-config.json) and falls back to the official Claude Code CLI settings located at ~/.claude/settings.json.
Renderer Process and UI State
The Renderer process is responsible for the visual representation of the AI's "thought" process and tool execution.
Streaming and Content Rendering
Real-time feedback is achieved by handling stream events. Partial message content is accumulated in the UI and rendered using ReactMarkdown with support for GitHub Flavored Markdown (GFM) and syntax highlighting.
- Content Blocks: The UI differentiates between
thinking,text, andtool_useblocks. - Skeleton States: While the agent is processing a stream, the UI displays a shimmer animation for visual feedback.
Sources: src/ui/App.tsx:49-75, src/ui/render/markdown.tsx:7-35, src/ui/components/EventCard.tsx:245-265
Tool-Use Permission System
A critical part of the architecture is the interactive decision panel for tool permissions. When the AI requests a sensitive action (like running a Bash command), the UI halts and presents a DecisionPanel.
Data Persistence
Agent Cowork maintains local state for cross-session continuity.
- SQLite Database: Used for storing full session history in WAL (Write-Ahead Logging) mode.
- Config Store: Manages API keys, base URLs, and model selection.
Sources: README_ZH.md:120-130, src/electron/libs/config-store.ts:40-66
API Configuration Schema
| Field | Type | Description |
|---|---|---|
apiKey | string | The authentication token for the AI model. |
baseURL | string | The endpoint URL for the API. |
model | string | The specific Claude model identifier (e.g., claude-3-5-sonnet). |
apiType | string | Optional identifier, defaults to "anthropic". |
Sources: src/electron/libs/config-store.ts:6-12
Summary
The High-Level Architecture of Agent Cowork leverages Electron to provide a bridge between the powerful capabilities of the Claude Agent SDK and a user-friendly desktop environment. By separating system-level tool execution in the Main process from the stateful, reactive UI in the Renderer process, the application ensures that complex AI-driven tasks (like file management and coding) are executed safely while providing transparent, real-time feedback to the user.