How opencoworkai/open-cowork works
1. What this repo is
- Open Cowork is an Electron desktop application for local AI agent work on Windows and macOS.
- The application is split into three runtime layers: main process (Node.js), preload bridge, and renderer UI (React + Vite).
2. Primary runtime boundary
- src/main owns all privileged operations: filesystem access, model calls, session state, sandbox execution, remote integrations, memory, and skills.
- src/renderer is the user-facing UI and only talks to the main process through IPC.
- src/preload/index.ts is the security boundary that exposes a controlled API into the renderer.
3. User interaction and event flow
- A user enters prompts, config, or file actions in the renderer.
- The renderer sends requests over IPC.
- The main process runs the agent/session logic, streams message and trace updates back, and the UI renders chat, tool results, permissions, and context panels.
4. Agent orchestration
- The core AI execution path lives in src/main/claude, especially agent-runner.ts.
- This layer handles model interaction, message lifecycle, loop guards, “think” parsing, one-shot runs, and tool result formatting.
- It is the central coordinator that connects model responses to tool execution, memory lookup, and session persistence.
5. Tool execution and safe command handling
- src/main/tools is the execution layer for agent-requested actions.
- It includes generic tool dispatch plus sandbox-aware execution.
- File and command operations are constrained by workspace containment logic, so the agent cannot act arbitrarily on the host filesystem.
6. Sandbox and host protection
- The repo has a clear security boundary in src/main/sandbox.
- Basic protection uses path guards and containment checks.
- Enhanced isolation routes command execution through WSL2 on Windows or Lima on macOS, with sync/bridge code to move workspace state between host and VM.
- This sandbox layer is a major architectural feature, not just a utility.
7. Session, config, and persistence
- src/main/session manages conversation/session state, titles, and lifecycle.
- src/main/config stores API configuration, auth-related settings, provider routing, and permissions.
- src/main/db/database.ts provides the local persistence layer for app state and history.
- Together these form the app’s durable control plane: sessions, settings, and user preferences survive restarts.
8. Memory subsystem
- src/main/memory is a distinct subsystem for extracting, storing, and retrieving “core” and “experience” memory.
- It includes ingestion queues, prompts, retrievers, navigator logic, and a memory-specific LLM client.
- Memory is not the same as session history: it is a longer-lived knowledge layer that can influence future agent behavior.
9. Skills system
- Built-in Skills live under .claude/skills, with supporting orchestration in src/main/skills.
- Skills are packaged workflows for document-centric outputs such as PPTX, DOCX, XLSX, and PDF.
- The repo also includes a skill-creator skill for generating custom skills.
- This is effectively a plugin-like capability layer for structured document generation and file processing.
10. External integrations: MCP and remote control
- src/main/mcp manages Model Context Protocol connections to external tools/services such as browser or desktop app connectors.
- src/main/remote handles remote control channels, specifically Feishu/Lark and Slack, with gateway, router, tunnel, and OAuth components.
- These integrations extend the agent beyond local files into external services and collaboration channels.
11. GUI operation and automation
- The app includes automation-oriented code for interacting with desktop UIs, not just text and files.
- This is reflected in main-process modules such as the agent/runtime extensions, tool execution, and remote/sandbox coordination.
- In architecture terms, GUI operation is another execution channel beside file tools and model tools.
12. Renderer structure
- The UI is a React app with components for chat, settings, permissions, sidebar/navigation, context display, remote control, sandbox setup, and trace visualization.
- src/renderer/components/message renders structured agent output such as thinking blocks, tool uses, tool results, and code blocks.
- The renderer is optimized for observability: users can see both the conversational layer and the operational trace.
13. Shared types and utilities
- src/shared contains cross-process contracts: IPC types, path constraints, session titles, schedule task titles, and network helpers.
- This shared package is important because it defines the stable interface between renderer, preload, and main.
14. Build, packaging, and delivery
- The project uses Vite for the renderer, Electron Builder for installers, and includes scripts for notarization, Windows artifact creation, and packaging helpers.
- GitHub Actions automate CI, releases, website deployment, and related release tasks.
- The website/ directory is a separate documentation site, not part of the app runtime.
15. Testing and verification
- The repository has extensive tests across agent execution, config, sandboxing, MCP, memory, remote control, renderer behavior, and packaging scripts.
- The tests reflect the architectural boundaries: the app is validated at the IPC/session/tool/sandbox edges, which are the most important failure points for this kind of desktop agent.
Main entry points: main/index.ts Main entry · agent-runner.ts Agent runner · tool-executor.ts Tool executor · preload/index.ts Preload bridge
Components 18
Runtime layers
Electron main, preload, and renderer boundaries.
- Main entry · Starts the Electron app and wires core main-process services.
src/main/index.ts - Preload bridge · Security boundary that exposes a controlled API to the renderer.
src/preload/index.ts - Renderer app · Top-level React application shell for the desktop UI.
src/renderer/App.tsx - Shared contracts · IPC types, path rules, session titles, and shared network helpers used across processes.
src/shared/ipc-types.ts
Main control plane
Agent orchestration, persistence, and policy inside the main process.
- Agent runner · Central model loop: prompts, think parsing, tool dispatch, loop guards, and result formatting.
src/main/claude/agent-runner.ts - Session manager · Owns conversation lifecycle, titles, and cached session state.
src/main/session/session-manager.ts - Config store · Persists API, auth, routing, and permission configuration.
src/main/config/config-store.ts - Local DB · Local durable storage for app state and history.
src/main/db/database.ts - Workspace guard · Defines containment rules that limit file and command actions to approved workspace paths.
src/main/workspace-path-constraints.ts
Integrations
External tool, sandbox, memory, remote, and skills subsystems.
- Tool executor · Executes agent-requested tools and routes safe file or command operations.
src/main/tools/tool-executor.ts - Sandbox layer · Path guards, native execution, and VM-backed command isolation for Windows and macOS.
src/main/sandbox/index.ts - Memory system · Extracts, stores, and retrieves core and experience memory for future runs.
src/main/memory/memory-manager.ts - Skills system · Loads built-in document and file-processing skills plus plugin-style workflows.
src/main/skills/skills-manager.ts - MCP manager · Manages Model Context Protocol connections and OAuth-enabled tool services.
src/main/mcp/mcp-manager.ts - Remote control · Routes Feishu/Lark and Slack remote control, gateway, and tunnel flows.
src/main/remote/remote-manager.ts
Renderer UI
React interface and observability panels.
- Chat view · Renders prompts, assistant turns, and structured agent output.
src/renderer/components/ChatView.tsx - Message blocks · Shows thinking, tool use, tool results, code, and other structured blocks.
src/renderer/components/message/ContentBlockView.tsx - Side panels · Holds settings, permissions, context, sandbox setup, remote control, and diagnostics panels.
src/renderer/components/Sidebar.tsx
Connections 23
- Main entry → Agent runner: starts orchestration · Bootstraps the main-process agent runtime.
- Main entry → Session manager: loads sessions · Initializes session lifecycle and persistence.
- Main entry → Config store: loads config · Reads app configuration and routing state.
- Main entry → Tool executor: registers tools · Connects execution services used by the agent.
- Main entry → MCP manager: starts connectors · Brings up external protocol connections.
- Main entry → Remote control: starts channels · Starts remote collaboration and control services.
- Preload bridge → Shared contracts: exposes api · Uses shared IPC contracts to define the renderer surface.
- Renderer app → Preload bridge: ipc calls · Renderer only talks to the main process through the preload API.
- Chat view → Preload bridge: send prompt · Submits chat and action requests through IPC.
- Message blocks → Chat view: renders stream · Displays streaming structured output inside the chat view.
- Side panels → Preload bridge: settings ipc · Settings, permissions, sandbox, and remote UI call into main.
- Agent runner → Tool executor: calls tools · Dispatches tool requests produced by model responses.
- Agent runner → Memory system: queries memory · Retrieves and updates long-lived agent memory.
- Agent runner → Session manager: updates session · Persists message lifecycle and session metadata.
- Tool executor → Workspace guard: checks paths · Enforces workspace containment before file or command execution.
- Tool executor → Sandbox layer: routes execution · Uses sandbox-aware execution for constrained command handling.
- Sandbox layer → Shared contracts: path rules · Shares path and IPC constraints with surrounding layers.
- Memory system → Local DB: stores memory · Persists extracted knowledge and state.
- Session manager → Local DB: persists state · Stores sessions, titles, and cached history.
- Config store → Local DB: persists settings · Saves configuration and permission state.
- Skills system → Tool executor: skill workflows · Invokes structured document and file-processing workflows through tool execution.
- MCP manager → Agent runner: tool context · Extends the agent with external tool sources.
- Remote control → Side panels: status ui · Remote control state is surfaced in the renderer panels.