# jasonkneen/cluso architecture

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

- Interactive diagram: https://gitdiagram.com/jasonkneen/cluso
- Repository: https://github.com/jasonkneen/cluso

## Overview

1. **Overall shape**  
Cluso is a monorepo for an AI coding assistant that runs in two main modes: a desktop app built with Electron and a browser/PWA-style web app. The UI is React-based, while privileged capabilities live in Electron or server-side packages.

2. **Frontend shell and feature composition**  
The root React app is centered on `App.tsx`, with UI in `components/` and behavior split into many small `features/*` hooks. This is a state-and-effects architecture: components render panels and dialogs, while feature hooks own synchronization, side effects, and runtime coordination.

3. **Runtime abstraction boundary**  
A key architectural boundary is the adapter layer in `lib/adapters/` and `src/adapters/`, which separates browser-safe logic from Electron-specific capabilities. The same product can run against a web adapter or an Electron adapter, so the diagram should show a shared frontend core with runtime-specific backends.

4. **Electron privileged backend**  
The `electron/` directory is the desktop control plane. `main.cjs`, `preload.cjs`, IPC handlers, file watching, PTY/terminal integration, LSP bridging, OAuth, patch history, and background validation all live here. This layer owns filesystem access, local process control, and OS-integrated workflows that the UI cannot do directly.

5. **AI assistant and agent loop**  
AI interaction is spread across `hooks/useAIChat*`, `hooks/useClusoAgent`, `services/clusoAgent.ts`, and feature modules like `features/agent`, `features/chat`, `features/tools`, `features/tool-calls`, `features/patches`, and `features/changes`. User messages and context become model requests, tool calls, clarifying questions, and code patches, then return as UI state updates and approved edits.

6. **Tool execution and approvals**  
The assistant is not just chat; it runs a tool pipeline. `shared-tools`, `utils/toolRouter.ts`, `utils/toolExecutionQueue.ts`, and approval-related features model a controlled execution flow where tools are grouped, dispatched, monitored, and sometimes require explicit user approval before changes land.

7. **Local code intelligence**  
Code understanding is backed by dedicated local services: `packages/lsp` for language server support, `packages/mgrep-local` for indexed search/semantic retrieval, and `packages/fast-apply` for patch application/editing. In the architecture, these sit behind the Electron/server boundary and feed context back into the AI loop.

8. **Element selection and browser integration**  
The app’s “intelligent element selection” is a major subsystem, not a minor UI detail. It uses `packages/shared-inspector`, `features/selection`, `features/selector-agent`, webview-related features, and a Chrome extension package under `packages/chrome-extension`. That extension provides content scripts, popup UI, devtools integration, and injected helpers to inspect DOM/react-fiber state and relay element data back to Cluso.

9. **Browser/webview and internal window orchestration**  
The `features/webview`, `features/viewport`, `features/internal-windows`, `features/navigation`, and `components/multi-viewport` areas coordinate embedded browser views and internal panes. This is the bridge between the assistant and the target page/app being inspected or manipulated.

10. **Local server and websocket mode**  
`packages/serve` is a standalone server package with HTTP routes for AI, files, git, backup, and OAuth, plus a websocket manager for live updates. This is the main non-Electron runtime boundary, used when the product needs a service process instead of direct desktop IPC.

11. **Shared package layer**  
Several packages are intentionally cross-cutting: `shared-types` defines messaging and element contracts, `shared-tools` standardizes tool routing and timeouts, and `shared-audio` supports voice/TTS-related functionality. These packages keep the Electron app, web app, extension, and server aligned on data shape and protocol.

12. **Data and persistence flow**  
Most state is local and workspace-oriented: files, patches, git state, settings, onboarding state, backup/recovery artifacts, and session logs. The diagram should show the user workspace as the source of truth, with the AI layer reading from it, proposing edits, and writing back through patch/file/git pathways.

13. **External services**  
The repo integrates with AI providers and OAuth-based services rather than a single fixed backend. Notable external touchpoints include Claude/AI SDK-based chat/agent flows, optional proxying via `cloudflare-worker/`, and OAuth for account-based integrations. These are supporting services around the core local-first desktop/browser architecture.

Main entry points: [`features`](https://github.com/jasonkneen/cluso/tree/main/features) (Feature hooks), [`services/clusoAgent.ts`](https://github.com/jasonkneen/cluso/blob/main/services/clusoAgent.ts) (Agent loop), [`lib/adapters`](https://github.com/jasonkneen/cluso/tree/main/lib/adapters) (Adapters), [`electron`](https://github.com/jasonkneen/cluso/tree/main/electron) (Electron core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_app_shell["App shell<br/>React entry<br/>[App.tsx]"]
  node_feature_layer["Feature hooks<br/>State/effects"]
  node_ui_components["UI components<br/>React panels"]
  node_adapter_boundary["Adapters<br/>Runtime bridge"]
end

subgraph group_desktop["Desktop"]
  node_electron_main["Electron core<br/>Desktop runtime"]
end

subgraph group_services["Services"]
  node_agent_loop["Agent loop<br/>AI orchestration<br/>[clusoAgent.ts]"]
  node_tool_pipeline["Tool pipeline<br/>Execution control<br/>[toolRouter.ts]"]
  node_patch_flow["Patch flow<br/>Edit workflow"]
  node_serve_backend["Serve backend<br/>HTTP/ws server"]
  node_workspace_state[("Workspace state<br/>Local source<br/>[FileService.ts]")]
  node_cloud_proxy["Cloud proxy<br/>Edge relay<br/>[codex-proxy.js]"]
end

subgraph group_packages["Packages"]
  node_local_intel["Local intelligence<br/>Code context"]
  node_shared_contracts["Shared contracts<br/>Protocol/types"]
  node_shared_tools["Shared tools<br/>Tooling core"]
  node_shared_audio["Audio<br/>Voice support"]
  node_mgrep_service["Mgrep<br/>Search index"]
  node_fast_apply_pkg["Fast apply<br/>Patch engine"]
end

subgraph group_browser["Browser"]
  node_webview_stack["Webviews<br/>Embedded browser"]
  node_selector_system["Element select<br/>Inspector bridge"]
  node_chrome_extension["Extension"]
end

node_app_shell -->|"renders"| node_ui_components
node_app_shell -->|"drives"| node_feature_layer
node_feature_layer -->|"uses"| node_adapter_boundary
node_adapter_boundary -->|"electron"| node_electron_main
node_adapter_boundary -->|"web"| node_serve_backend
node_electron_main -->|"controls"| node_workspace_state
node_serve_backend -->|"serves"| node_workspace_state
node_feature_layer -->|"coordinates"| node_agent_loop
node_agent_loop -->|"dispatches"| node_tool_pipeline
node_tool_pipeline -->|"shares"| node_shared_tools
node_tool_pipeline -->|"feeds"| node_patch_flow
node_patch_flow -->|"applies"| node_fast_apply_pkg
node_agent_loop -->|"queries"| node_local_intel
node_local_intel -->|"search"| node_mgrep_service
node_local_intel -->|"edits"| node_fast_apply_pkg
node_feature_layer -->|"coordinates"| node_webview_stack
node_webview_stack -->|"inspects"| node_selector_system
node_selector_system -->|"bridges"| node_chrome_extension
node_selector_system -->|"formats"| node_shared_contracts
node_agent_loop -.->|"optionally routes"| node_cloud_proxy
node_serve_backend -->|"aligns on"| node_shared_contracts
node_feature_layer -->|"uses"| node_shared_audio
node_electron_main -->|"shares"| node_shared_contracts

click node_app_shell "https://github.com/jasonkneen/cluso/blob/main/App.tsx"
click node_feature_layer "https://github.com/jasonkneen/cluso/tree/main/features"
click node_ui_components "https://github.com/jasonkneen/cluso/tree/main/components"
click node_adapter_boundary "https://github.com/jasonkneen/cluso/tree/main/lib/adapters"
click node_electron_main "https://github.com/jasonkneen/cluso/tree/main/electron"
click node_webview_stack "https://github.com/jasonkneen/cluso/tree/main/features/webview"
click node_selector_system "https://github.com/jasonkneen/cluso/tree/main/packages/shared-inspector"
click node_chrome_extension "https://github.com/jasonkneen/cluso/tree/main/packages/chrome-extension"
click node_agent_loop "https://github.com/jasonkneen/cluso/blob/main/services/clusoAgent.ts"
click node_tool_pipeline "https://github.com/jasonkneen/cluso/blob/main/utils/toolRouter.ts"
click node_patch_flow "https://github.com/jasonkneen/cluso/tree/main/features/patches"
click node_local_intel "https://github.com/jasonkneen/cluso/tree/main/packages/lsp"
click node_serve_backend "https://github.com/jasonkneen/cluso/tree/main/packages/serve"
click node_shared_contracts "https://github.com/jasonkneen/cluso/tree/main/packages/shared-types"
click node_shared_tools "https://github.com/jasonkneen/cluso/tree/main/packages/shared-tools"
click node_shared_audio "https://github.com/jasonkneen/cluso/tree/main/packages/shared-audio"
click node_workspace_state "https://github.com/jasonkneen/cluso/blob/main/services/FileService.ts"
click node_mgrep_service "https://github.com/jasonkneen/cluso/tree/main/packages/mgrep-local"
click node_fast_apply_pkg "https://github.com/jasonkneen/cluso/tree/main/packages/fast-apply"
click node_cloud_proxy "https://github.com/jasonkneen/cluso/blob/main/cloudflare-worker/codex-proxy.js"

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_app_shell,node_feature_layer,node_ui_components,node_adapter_boundary toneBlue
class node_electron_main toneAmber
class node_agent_loop,node_tool_pipeline,node_patch_flow,node_serve_backend,node_workspace_state,node_cloud_proxy toneMint
class node_local_intel,node_shared_contracts,node_shared_tools,node_shared_audio,node_mgrep_service,node_fast_apply_pkg toneRose
class node_webview_stack,node_selector_system,node_chrome_extension toneIndigo
```

## Components

### Frontend

React UI shell and feature/state orchestration

- [App shell](https://github.com/jasonkneen/cluso/blob/main/App.tsx): React entry · Top-level React composition and provider wiring · `App.tsx`
- [Feature hooks](https://github.com/jasonkneen/cluso/tree/main/features): State/effects · Primary UI behavior split across feature modules · `features`
- [UI components](https://github.com/jasonkneen/cluso/tree/main/components): React panels · Panels, dialogs, toolbars, and shared UI composition · `components`
- [Adapters](https://github.com/jasonkneen/cluso/tree/main/lib/adapters): Runtime bridge · Shared adapter layer separating web-safe logic from runtime-specific capabilities · `lib/adapters`

### Desktop

Electron privileged runtime and IPC boundary

- [Electron core](https://github.com/jasonkneen/cluso/tree/main/electron): Desktop runtime · Main process, preload, IPC, filesystem, terminal, OAuth, and validation · `electron`

### Services

AI, tool, patch, and workspace orchestration

- [Agent loop](https://github.com/jasonkneen/cluso/blob/main/services/clusoAgent.ts): AI orchestration · Chat, agent state, tool calls, clarifying questions, and coding context · `services/clusoAgent.ts`
- [Tool pipeline](https://github.com/jasonkneen/cluso/blob/main/utils/toolRouter.ts): Execution control · Tool routing, queuing, grouping, and approval gates · `utils/toolRouter.ts`
- [Patch flow](https://github.com/jasonkneen/cluso/tree/main/features/patches): Edit workflow · Patch generation, fast apply, approvals, and change tracking · `features/patches`
- [Serve backend](https://github.com/jasonkneen/cluso/tree/main/packages/serve): HTTP/ws server · Standalone server for AI, files, git, backup, and OAuth with websocket updates · `packages/serve`
- [Workspace state](https://github.com/jasonkneen/cluso/blob/main/services/FileService.ts): Local source · Files, git state, settings, sessions, patches, and persisted local workspace data · `services/FileService.ts`
- [Cloud proxy](https://github.com/jasonkneen/cluso/blob/main/cloudflare-worker/codex-proxy.js): Edge relay · Optional Cloudflare Worker proxy for external AI/service access · `cloudflare-worker/codex-proxy.js`

### Packages

Reusable local libraries and integrations

- [Local intelligence](https://github.com/jasonkneen/cluso/tree/main/packages/lsp): Code context · LSP, indexed search, and patch application services feeding the assistant · `packages/lsp`
- [Shared contracts](https://github.com/jasonkneen/cluso/tree/main/packages/shared-types): Protocol/types · Cross-runtime messaging, tool, element, and audio contracts · `packages/shared-types`
- [Shared tools](https://github.com/jasonkneen/cluso/tree/main/packages/shared-tools): Tooling core · Tool router helpers and execution timeouts shared across runtimes · `packages/shared-tools`
- [Audio](https://github.com/jasonkneen/cluso/tree/main/packages/shared-audio): Voice support · Shared voice and TTS-related functionality · `packages/shared-audio`
- [Mgrep](https://github.com/jasonkneen/cluso/tree/main/packages/mgrep-local): Search index · Local indexed search and semantic retrieval service · `packages/mgrep-local`
- [Fast apply](https://github.com/jasonkneen/cluso/tree/main/packages/fast-apply): Patch engine · Patch application and model-assisted editing package · `packages/fast-apply`

### Browser

Webview and extension-based inspection flows

- [Webviews](https://github.com/jasonkneen/cluso/tree/main/features/webview): Embedded browser · Viewport, navigation, and internal window orchestration · `features/webview`
- [Element select](https://github.com/jasonkneen/cluso/tree/main/packages/shared-inspector): Inspector bridge · DOM/react-fiber inspection and intelligent element selection · `packages/shared-inspector`
- [Extension](https://github.com/jasonkneen/cluso/tree/main/packages/chrome-extension): Browser extension · Content script, popup, devtools, and injected helpers · `packages/chrome-extension`

## Connections

- App shell → UI components: renders · The app shell composes the visible UI panels and dialogs
- App shell → Feature hooks: drives · Root app wires feature hooks that own state and effects
- Feature hooks → Adapters: uses · Feature hooks call through runtime adapters for browser-safe access
- Adapters → Electron core: electron · Desktop runtime implementation provides privileged capabilities
- Adapters → Serve backend: web · Web runtime can target the standalone server boundary
- Electron core → Workspace state: controls · Electron owns filesystem, git, terminal, and local process access
- Serve backend → Workspace state: serves · Server exposes workspace-oriented APIs for files, git, backup, and OAuth
- Feature hooks → Agent loop: coordinates · Agent-related hooks and features manage model interaction and state updates
- Agent loop → Tool pipeline: dispatches · Assistant requests are converted into controlled tool execution
- Tool pipeline → Shared tools: shares · Common routing and timeout primitives standardize tool handling
- Tool pipeline → Patch flow: feeds · Tool outputs can become edits, approvals, and pending changes
- Patch flow → Fast apply: applies · Fast patch application performs local edits when approved
- Agent loop → Local intelligence: queries · The agent loop uses local code intelligence for context and retrieval
- Local intelligence → Mgrep: search · Indexed semantic retrieval backs code understanding
- Local intelligence → Fast apply: edits · Patch tooling is part of the local intelligence/editing path
- Feature hooks → Webviews: coordinates · Navigation and viewport features manage embedded browser targets
- Webviews → Element select: inspects · Webview and selection flows rely on DOM/react-fiber inspection
- Element select → Extension: bridges · Extension package captures page data and relays it back to Cluso
- Element select → Shared contracts: formats · Element contracts are shared across extension, UI, and backend
- Agent loop → Cloud proxy: optionally routes · External model access can be proxied through edge infrastructure
- Serve backend → Shared contracts: aligns on · Server APIs use shared message and element schemas
- Feature hooks → Audio: uses · Voice and TTS features consume shared audio support
- Electron core → Shared contracts: shares · Desktop IPC and bridge code depend on common contracts
