Installation and Setup
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Agent Cowork is an open-source desktop AI collaboration partner designed as a visual alternative to Claude Code. It provides a native GUI for managing programming tasks, file operations, and multi-step AI sessions. The application is built using Electron 39, React 19, and Tailwind CSS 4, utilizing the @anthropic-ai/claude-agent-sdk for its core intelligence.
The setup process focuses on two primary paths: utilizing pre-built releases for immediate use or building from source for development. A key feature of the installation is its compatibility with existing Claude Code configurations, allowing users to reuse authenticated environments and API settings seamlessly.
Sources: README.md:1-40, README_ZH.md:85-100
Prerequisites
Before installing or building Agent Cowork, the following environment requirements must be met:
- Runtime Environment: Bun (preferred) or Node.js (Version 22+ recommended; Version 18+ minimum support).
- Claude Code CLI: Must be installed and authenticated on the local system.
- Operating System: macOS (Apple Silicon/Intel), Windows, or Linux.
Sources: README.md:46-48, README_ZH.md:44-46
Installation Methods
Option 1: Using Binary Releases
Users can download pre-compiled binaries for their specific platform from the GitHub Releases page. This method does not require a development environment or manual Claude Code installation within the application directory.
Sources: README.md:41-43
Option 2: Building from Source
Building from source involves cloning the repository, installing dependencies via Bun, and executing platform-specific build scripts.
The diagram shows the transition from source code to either a local development environment or production-ready binaries.
Sources: README.md:50-70, package.json:7-21
Build and Distribution Scripts
The project uses electron-builder for packaging and vite for frontend bundling.
| Command | Purpose |
|---|---|
bun run dev | Starts Vite dev server and Electron in development mode with hot reload. |
bun run build | Compiles TypeScript and runs Vite production build. |
bun run dist:mac-arm64 | Generates a DMG for Apple Silicon macOS. |
bun run dist:win | Generates a portable Windows executable. |
bun run dist:linux | Generates an AppImage for Linux. |
| Sources: package.json:7-21, electron-builder.json:1-25 |
API and Environment Configuration
Configuration Resolution Logic
Agent Cowork manages API settings through a hierarchical resolution system. It first checks for application-specific UI settings, then falls back to the local system's Claude settings.
The flow describes how the application prioritizes user-defined UI settings over CLI-based configuration files.
Sources: src/electron/libs/claude-settings.ts:24-60
Key Configuration Parameters
API configuration is stored in api-config.json within the user data path.
| Parameter | Type | Description |
|---|---|---|
apiKey | String | Anthropic API Key (or compatible provider token). |
baseURL | String | API endpoint URL (supports third-party proxies). |
model | String | Model identifier (e.g., claude-3-5-sonnet-20241022). |
apiType | Enum | Defaults to "anthropic". |
| Sources: src/electron/libs/config-store.ts:6-12, src/ui/components/SettingsModal.tsx:45-55 |
Manual Configuration via UI
If no configuration is detected on startup, the SettingsModal is triggered. Users can provide the Base URL, API Key, and Model Name directly. The UI validates the URL format and existence of required fields before persisting the data via the save-api-config IPC handle.
Sources: src/ui/components/SettingsModal.tsx:39-80, src/electron/main.ts:121-135
Internal Setup Mechanisms
Asset and SDK Path Resolution
The application dynamically resolves the path to the Claude Code CLI based on whether the app is packaged or in development.
- Packaged: Points to
app.asar.unpacked/node_modules/@anthropic-ai/claude-agent-sdk/cli.js. - Development: Points to the local
node_modulesdirectory.
Sources: src/electron/libs/claude-settings.ts:7-19, electron-builder.json:10-12
Environment Variable Injection
When a session is initiated, the application builds an execution environment by merging system environment variables with API-specific tokens.
export function buildEnvForConfig(config: ApiConfig): Record<string, string> {
const baseEnv = { ...process.env } as Record<string, string>;
baseEnv.ANTHROPIC_AUTH_TOKEN = config.apiKey;
baseEnv.ANTHROPIC_BASE_URL = config.baseURL;
baseEnv.ANTHROPIC_MODEL = config.model;
return baseEnv;
}
Sources: src/electron/libs/claude-settings.ts:71-79
Summary
Setting up Agent Cowork requires a functional Node.js or Bun environment and an authenticated Claude Code installation. The application provides robust flexibility by allowing users to either inherit settings from the official CLI or override them via a dedicated UI. By leveraging electron-builder and better-sqlite3, the system ensures that both the installation and subsequent data persistence are performant and cross-platform compatible.