# opencoworkai/open-cowork architecture

> Architecture diagram of the GitHub repository opencoworkai/open-cowork, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/opencoworkai/open-cowork
- Repository: https://github.com/opencoworkai/open-cowork

## Overview

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: [`src/main/index.ts`](https://github.com/opencoworkai/open-cowork/blob/main/src/main/index.ts) (Main entry), [`src/main/claude/agent-runner.ts`](https://github.com/opencoworkai/open-cowork/blob/main/src/main/claude/agent-runner.ts) (Agent runner), [`src/main/tools/tool-executor.ts`](https://github.com/opencoworkai/open-cowork/blob/main/src/main/tools/tool-executor.ts) (Tool executor), [`src/preload/index.ts`](https://github.com/opencoworkai/open-cowork/blob/main/src/preload/index.ts) (Preload bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime layers"]
  node_main_entry["Main entry<br/>electron bootstrap<br/>[index.ts]"]
  node_preload_bridge["Preload bridge<br/>ipc bridge<br/>[index.ts]"]
  node_renderer_app["Renderer app<br/>react ui<br/>[App.tsx]"]
  node_shared_contracts["Shared contracts<br/>cross-process types<br/>[ipc-types.ts]"]
end

subgraph group_control["Main control plane"]
  node_agent_runner["Agent runner<br/>claude orchestration<br/>[agent-runner.ts]"]
  node_session_mgr["Session manager<br/>session state<br/>[session-manager.ts]"]
  node_config_store[("Config store<br/>settings store<br/>[config-store.ts]")]
  node_database[("Local DB<br/>persistence<br/>[database.ts]")]
  node_workspace_constraints["Workspace guard<br/>path policy"]
end

subgraph group_integrations["Integrations"]
  node_tool_exec["Tool executor<br/>tool dispatch<br/>[tool-executor.ts]"]
  node_sandbox["Sandbox layer<br/>isolation<br/>[index.ts]"]
  node_memory["Memory system<br/>long-lived memory<br/>[memory-manager.ts]"]
  node_skills["Skills system<br/>workflow plugins<br/>[skills-manager.ts]"]
  node_mcp["MCP manager<br/>external tools<br/>[mcp-manager.ts]"]
  node_remote["Remote control<br/>collaboration channels<br/>[remote-manager.ts]"]
end

subgraph group_ui["Renderer UI"]
  node_renderer_chat["Chat view<br/>conversation ui<br/>[ChatView.tsx]"]
  node_renderer_message["Message blocks<br/>trace ui"]
  node_renderer_panels["Side panels<br/>settings and status ui<br/>[Sidebar.tsx]"]
end

node_main_entry -->|"starts orchestration"| node_agent_runner
node_main_entry -->|"loads sessions"| node_session_mgr
node_main_entry -->|"loads config"| node_config_store
node_main_entry -->|"registers tools"| node_tool_exec
node_main_entry -->|"starts connectors"| node_mcp
node_main_entry -->|"starts channels"| node_remote
node_preload_bridge -->|"exposes api"| node_shared_contracts
node_renderer_app -->|"ipc calls"| node_preload_bridge
node_renderer_chat -->|"send prompt"| node_preload_bridge
node_renderer_message -->|"renders stream"| node_renderer_chat
node_renderer_panels -->|"settings ipc"| node_preload_bridge
node_agent_runner -->|"calls tools"| node_tool_exec
node_agent_runner -->|"queries memory"| node_memory
node_agent_runner -->|"updates session"| node_session_mgr
node_tool_exec -->|"checks paths"| node_workspace_constraints
node_tool_exec -->|"routes execution"| node_sandbox
node_sandbox -->|"path rules"| node_shared_contracts
node_memory -->|"stores memory"| node_database
node_session_mgr -->|"persists state"| node_database
node_config_store -->|"persists settings"| node_database
node_skills -->|"skill workflows"| node_tool_exec
node_mcp -.->|"tool context"| node_agent_runner
node_remote -.->|"status ui"| node_renderer_panels

click node_main_entry "https://github.com/opencoworkai/open-cowork/blob/main/src/main/index.ts"
click node_preload_bridge "https://github.com/opencoworkai/open-cowork/blob/main/src/preload/index.ts"
click node_renderer_app "https://github.com/opencoworkai/open-cowork/blob/main/src/renderer/App.tsx"
click node_agent_runner "https://github.com/opencoworkai/open-cowork/blob/main/src/main/claude/agent-runner.ts"
click node_session_mgr "https://github.com/opencoworkai/open-cowork/blob/main/src/main/session/session-manager.ts"
click node_config_store "https://github.com/opencoworkai/open-cowork/blob/main/src/main/config/config-store.ts"
click node_database "https://github.com/opencoworkai/open-cowork/blob/main/src/main/db/database.ts"
click node_workspace_constraints "https://github.com/opencoworkai/open-cowork/blob/main/src/main/workspace-path-constraints.ts"
click node_tool_exec "https://github.com/opencoworkai/open-cowork/blob/main/src/main/tools/tool-executor.ts"
click node_sandbox "https://github.com/opencoworkai/open-cowork/blob/main/src/main/sandbox/index.ts"
click node_memory "https://github.com/opencoworkai/open-cowork/blob/main/src/main/memory/memory-manager.ts"
click node_skills "https://github.com/opencoworkai/open-cowork/blob/main/src/main/skills/skills-manager.ts"
click node_mcp "https://github.com/opencoworkai/open-cowork/blob/main/src/main/mcp/mcp-manager.ts"
click node_remote "https://github.com/opencoworkai/open-cowork/blob/main/src/main/remote/remote-manager.ts"
click node_renderer_chat "https://github.com/opencoworkai/open-cowork/blob/main/src/renderer/components/ChatView.tsx"
click node_renderer_message "https://github.com/opencoworkai/open-cowork/blob/main/src/renderer/components/message/ContentBlockView.tsx"
click node_renderer_panels "https://github.com/opencoworkai/open-cowork/blob/main/src/renderer/components/Sidebar.tsx"
click node_shared_contracts "https://github.com/opencoworkai/open-cowork/blob/main/src/shared/ipc-types.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_entry,node_preload_bridge,node_renderer_app,node_shared_contracts toneBlue
class node_agent_runner,node_session_mgr,node_config_store,node_database,node_workspace_constraints toneAmber
class node_tool_exec,node_sandbox,node_memory,node_skills,node_mcp,node_remote toneMint
class node_renderer_chat,node_renderer_message,node_renderer_panels toneRose
```

## Components

### Runtime layers

Electron main, preload, and renderer boundaries.

- [Main entry](https://github.com/opencoworkai/open-cowork/blob/main/src/main/index.ts): electron bootstrap · Starts the Electron app and wires core main-process services. · `src/main/index.ts`
- [Preload bridge](https://github.com/opencoworkai/open-cowork/blob/main/src/preload/index.ts): ipc bridge · Security boundary that exposes a controlled API to the renderer. · `src/preload/index.ts`
- [Renderer app](https://github.com/opencoworkai/open-cowork/blob/main/src/renderer/App.tsx): react ui · Top-level React application shell for the desktop UI. · `src/renderer/App.tsx`
- [Shared contracts](https://github.com/opencoworkai/open-cowork/blob/main/src/shared/ipc-types.ts): cross-process types · 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](https://github.com/opencoworkai/open-cowork/blob/main/src/main/claude/agent-runner.ts): claude orchestration · Central model loop: prompts, think parsing, tool dispatch, loop guards, and result formatting. · `src/main/claude/agent-runner.ts`
- [Session manager](https://github.com/opencoworkai/open-cowork/blob/main/src/main/session/session-manager.ts): session state · Owns conversation lifecycle, titles, and cached session state. · `src/main/session/session-manager.ts`
- [Config store](https://github.com/opencoworkai/open-cowork/blob/main/src/main/config/config-store.ts): settings store · Persists API, auth, routing, and permission configuration. · `src/main/config/config-store.ts`
- [Local DB](https://github.com/opencoworkai/open-cowork/blob/main/src/main/db/database.ts): persistence · Local durable storage for app state and history. · `src/main/db/database.ts`
- [Workspace guard](https://github.com/opencoworkai/open-cowork/blob/main/src/main/workspace-path-constraints.ts): path policy · 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](https://github.com/opencoworkai/open-cowork/blob/main/src/main/tools/tool-executor.ts): tool dispatch · Executes agent-requested tools and routes safe file or command operations. · `src/main/tools/tool-executor.ts`
- [Sandbox layer](https://github.com/opencoworkai/open-cowork/blob/main/src/main/sandbox/index.ts): isolation · Path guards, native execution, and VM-backed command isolation for Windows and macOS. · `src/main/sandbox/index.ts`
- [Memory system](https://github.com/opencoworkai/open-cowork/blob/main/src/main/memory/memory-manager.ts): long-lived memory · Extracts, stores, and retrieves core and experience memory for future runs. · `src/main/memory/memory-manager.ts`
- [Skills system](https://github.com/opencoworkai/open-cowork/blob/main/src/main/skills/skills-manager.ts): workflow plugins · Loads built-in document and file-processing skills plus plugin-style workflows. · `src/main/skills/skills-manager.ts`
- [MCP manager](https://github.com/opencoworkai/open-cowork/blob/main/src/main/mcp/mcp-manager.ts): external tools · Manages Model Context Protocol connections and OAuth-enabled tool services. · `src/main/mcp/mcp-manager.ts`
- [Remote control](https://github.com/opencoworkai/open-cowork/blob/main/src/main/remote/remote-manager.ts): collaboration channels · 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](https://github.com/opencoworkai/open-cowork/blob/main/src/renderer/components/ChatView.tsx): conversation ui · Renders prompts, assistant turns, and structured agent output. · `src/renderer/components/ChatView.tsx`
- [Message blocks](https://github.com/opencoworkai/open-cowork/blob/main/src/renderer/components/message/ContentBlockView.tsx): trace ui · Shows thinking, tool use, tool results, code, and other structured blocks. · `src/renderer/components/message/ContentBlockView.tsx`
- [Side panels](https://github.com/opencoworkai/open-cowork/blob/main/src/renderer/components/Sidebar.tsx): settings and status ui · Holds settings, permissions, context, sandbox setup, remote control, and diagnostics panels. · `src/renderer/components/Sidebar.tsx`

## Connections

- 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.