How jasonkneen/cluso works
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 Feature hooks · clusoAgent.ts Agent loop · adapters Adapters · electron Electron core
Components 20
Frontend
React UI shell and feature/state orchestration
- App shell · Top-level React composition and provider wiring
App.tsx - Feature hooks · Primary UI behavior split across feature modules
features - UI components · Panels, dialogs, toolbars, and shared UI composition
components - Adapters · Shared adapter layer separating web-safe logic from runtime-specific capabilities
lib/adapters
Desktop
Electron privileged runtime and IPC boundary
- Electron core · Main process, preload, IPC, filesystem, terminal, OAuth, and validation
electron
Services
AI, tool, patch, and workspace orchestration
- Agent loop · Chat, agent state, tool calls, clarifying questions, and coding context
services/clusoAgent.ts - Tool pipeline · Tool routing, queuing, grouping, and approval gates
utils/toolRouter.ts - Patch flow · Patch generation, fast apply, approvals, and change tracking
features/patches - Serve backend · Standalone server for AI, files, git, backup, and OAuth with websocket updates
packages/serve - Workspace state · Files, git state, settings, sessions, patches, and persisted local workspace data
services/FileService.ts - Cloud proxy · Optional Cloudflare Worker proxy for external AI/service access
cloudflare-worker/codex-proxy.js
Packages
Reusable local libraries and integrations
- Local intelligence · LSP, indexed search, and patch application services feeding the assistant
packages/lsp - Shared contracts · Cross-runtime messaging, tool, element, and audio contracts
packages/shared-types - Shared tools · Tool router helpers and execution timeouts shared across runtimes
packages/shared-tools - Audio · Shared voice and TTS-related functionality
packages/shared-audio - Mgrep · Local indexed search and semantic retrieval service
packages/mgrep-local - Fast apply · Patch application and model-assisted editing package
packages/fast-apply
Browser
Webview and extension-based inspection flows
- Webviews · Viewport, navigation, and internal window orchestration
features/webview - Element select · DOM/react-fiber inspection and intelligent element selection
packages/shared-inspector - Extension · Content script, popup, devtools, and injected helpers
packages/chrome-extension
Connections 23
- 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