Introduction to Agent Cowork
Relevant source files
The following files were used as context for generating this wiki page:
Agent Cowork is an open-source desktop AI assistant designed as a visual alternative to the terminal-based Claude Code. It serves as a collaborative AI partner capable of handling multi-step tasks such as programming, file management, and command execution. The system provides visual feedback for complex AI operations, persistent session management across projects, and interactive tool inspection that is often missing in CLI environments.
The application is built to be "not just a GUI," but a real-time collaboration environment where tool outputs are easy to inspect and multiple sessions can be tracked simultaneously. It maintains high compatibility with existing Claude Code configurations by reusing settings files and environment variables.
Sources: README.md:21-36, README_ZH.md:55-64
System Architecture
Agent Cowork is architected as a cross-platform desktop application using Electron 39. It utilizes a decoupled structure where the frontend (Renderer) and backend (Main Process) communicate via Inter-Process Communication (IPC).
High-Level Architecture Overview
The following diagram illustrates the relationship between the user interface, the Electron main process, and the underlying AI SDK.
Core Technology Stack
| Layer | Technology | Description |
|---|---|---|
| Framework | Electron 39 | Cross-platform desktop environment. |
| Frontend | React 19 / Tailwind CSS 4 | UI rendering and styling. |
| State Management | Zustand | Frontend application state. |
| Database | better-sqlite3 | Local session and message history storage using WAL mode. |
| AI Integration | @anthropic-ai/claude-agent-sdk | Core AI logic and tool handling. |
| Build System | Vite / Bun | Development and distribution toolchain. |
| Sources: README_ZH.md:117-126, package.json:37-55 |
Session Management and Persistence
The system implements a robust session management system that allows users to create, resume, and delete tasks. Each session is tied to a specific working directory (CWD) and maintains its own history.
Database Schema
Persistence is handled through an SQLite database. The schema consists of two primary tables: sessions and messages.
Session Life Cycle
- Creation: A session is initialized with a title, directory, and initial prompt.
- Execution: The session status moves to
running. Messages and tool results are recorded in real-time. - Persistence: Every message (system, assistant, user, or tool result) is serialized and stored in the database.
- Resumption: Sessions can be reloaded from the history, or even resumed in the Claude Code CLI using a specific resume command.
Sources: src/electron/libs/session-store.ts:48-66, src/ui/components/Sidebar.tsx:50-65
AI Collaboration and Tool Permissions
A key feature of Agent Cowork is the interactive permission system. Unlike CLI tools that may execute commands automatically or require global flags, Agent Cowork provides a "Decision Panel" for sensitive operations.
Permission Request Flow
When the Claude Agent SDK attempts to use a tool (like Bash or Write), the Main process intercepts the request and sends it to the Renderer for user approval.
Tool Monitoring
Tool status is tracked visually using indicators:
- Pending: The tool is currently running or awaiting permission.
- Success: The tool completed execution.
- Error: The tool encountered an issue (e.g., command failed).
Sources: src/ui/components/EventCard.tsx:165-180
Configuration and Compatibility
Agent Cowork is designed to be fully compatible with Claude Code. It prioritizes user-defined UI configurations but provides a fallback to the standard Claude CLI settings file.
API Configuration Priority
- UI Configuration: Settings saved via the
SettingsModalin the app. - Local Settings File: Reuses
~/.claude/settings.json. - Environment Variables:
ANTHROPIC_AUTH_TOKEN,ANTHROPIC_BASE_URL, andANTHROPIC_MODEL.
Sources: src/electron/libs/claude-settings.ts:26-40, README_ZH.md:103-113
IPC API Definitions
The communication between layers is strictly typed via the Window.electron interface.
| Method | Return Type | Purpose |
|---|---|---|
getApiConfig | Promise<ApiConfig> | Retrieves current AI settings. |
saveApiConfig | Promise<{success: boolean}> | Updates local AI credentials. |
selectDirectory | Promise<string> | Opens native folder picker. |
generateSessionTitle | Promise<string> | Uses AI to summarize a task title. |
| Sources: types.d.ts:19-35 |
Conclusion
Agent Cowork provides a technical bridge between powerful AI agents and standard desktop workflows. By wrapping the @anthropic-ai/claude-agent-sdk in a modern Electron shell, it adds critical features for developer productivity, including persistent SQLite-based history, visual tool call tracking, and a granular permission system for local command execution. Its strict compatibility with Claude Code settings ensures a seamless transition for developers already using Anthropic's ecosystem.
Sources: README.md:21-42, README_ZH.md:8-15