DOCSEARCHbyAlgolia
Submit Docs

DeepChat Documentation

repository·dev·Indexed 26 days ago

https://github.com/thinkinaixyz/deepchat

DeepChat is an open-source, local-first desktop client for AI agents available for Windows, macOS, and Linux. It features session recoverability via Tape.systems, extensibility through Skills and Model Context Protocol (MCP), and remote control integration with messaging apps like Telegram, Discord, and WeChat iLink. The client supports cloud LLM providers (OpenAI, Gemini, Anthropic), local Ollama models, and ACP-compatible agents.

Tokens
160K
Snippets
191
Records
835
Agent score
91%

What's inside DeepChat

  1. Overview of DeepChat AI Agent Desktop Client

    dev

    DeepChat is an open-source, local-first AI agent desktop client designed for Windows, macOS, and Linux. It integrates various models (cloud APIs like OpenAI, Gemini, Anthropic or local Ollama models), tools, Skills, and agent runtimes into a single application.

    Key architectural philosophies include:

    • Tape.systems: Sessions and agent processes follow a 'Tape' philosophy, ensuring context, tool calls, and requests are recoverable, traceable, and inspectable.
    • Local-First: Designed to run agents, ACP agents, and remote-ready bots locally while maintaining privacy through local data storage and network proxy support.
    • Multi-Model Management: Supports mainstream cloud LLMs and local Ollama models in one interface.

  2. Overview of DeepChat

    dev
    DeepChat is an open-source, local-first desktop client for AI Agents. It unifies models (cloud APIs like OpenAI/Gemini/Anthropic or local Ollama models), tools, Skills, Agent Runtimes, and long-running sessions into a single application. It is designed around the Tape.systems philosophy, ensuring that agent processes, tool calls, and context are recoverable, traceable, and auditable.

  3. Understand ACP v1 Integration in DeepChat

    dev

    DeepChat integrates with the Agent Client Protocol (ACP) v1 to connect with various agents like DimCode, Claude Code ACP, and Codex ACP.

    Key Integration Concepts:

    • Capability-Based Execution: DeepChat uses the capabilities returned during the initialize phase to determine which protocol methods (e.g., file system, terminals, tool calls) are available. It only calls methods for which the agent has explicitly declared support.
    • Session Management: Remote ACP sessions are treated as external resources. DeepChat performs workspace-level import, synchronization, and binding. Once imported, remote sessions are converted into DeepChat's internal message format and persisted. DeepChat acts as the source of truth for conversation data to prevent overwriting user-maintained data with remote metadata.
    • Authentication: For agents requiring authentication (like Claude Code ACP), DeepChat provides a way to complete the agent's exposed authentication flow directly within the interface.

  4. Understand the DeepChat project structure

    dev

    The project is organized into several key directories:

    • src/main/: Electron main process. Contains Presenters, typed route handlers, runtime orchestration, and persistence (window, tab, thread, config, llmProvider, mcp, knowledge, etc.).
    • src/preload/: The bridge layer with contextIsolation enabled. Exposes the typed window.deepchat API to the renderer.
    • src/renderer/: Vue 3 + Pinia application.
      • src/renderer/src/: Core UI code (components, stores, views, lib, i18n).
      • src/renderer/shell/: Shell UI components.
      • src/renderer/api/: The boundary layer between renderer and main. Contains typed *Client implementations, event subscriptions, and runtime wrappers. src/renderer/api/legacy/ is for compatibility only.
    • src/shared/: Shared route contracts, event contracts, types, and utilities.
    • runtime/: MCP/Agent runtimes (Node/uv) shipped with the app.
    • test/: Vitest tests for both main and renderer processes.

  5. Understand the Tool, MCP, Skill, and Plugin Architecture

    dev

    DeepChat organizes its extension and execution capabilities into four distinct modules. Understanding their ownership is critical for managing tool lifecycles and permissions:

    • Tool (src/main/tool/): Manages the catalog, source mapping, execution, permissions, and local Agent tools.
    • MCP (src/main/mcp/): Manages the lifecycle of MCP (Model Context Protocol) servers/clients, OAuth, configuration, and MCP tool calls.
    • Skill (src/main/skill/): Acts as the process-level owner for per-Agent Skill roots, scanning, snapshot imports, and Plugin contributions.
    • Plugin (src/main/plugin/): Handles package installation status, manifest validation, and capability registration. Note that Plugins only register capabilities; they do not manage the running state of MCP, Skills, or Tools.

    Isolation Note: Skills, catalog caches, watchers, and enablement are isolated per DeepChat Agent. Sessions only save the selected Skill name and cannot access another Agent's root.

  6. Understand DeepChat Renderer Locale Lazy Loading

    dev
    DeepChat uses a lazy-loading mechanism for renderer language packs to optimize performance and bundle size. Instead of statically importing all 20+ language packs (which previously totaled ~5.4 MB), the application now dynamically loads only the current locale and the en-US fallback at startup. This prevents the Settings renderer and main window from being bloated by unused translation resources.

  7. Understand the Chat Scroll Ownership Architecture

    dev

    DeepChat uses a centralized scroll ownership model to prevent layout jumps, flashing, or scrollbar hijacking during chat interactions (such as streaming updates, loading history, or resizing the composer).

    Key architectural principles include:

    • Single Scroll Owner: The message viewport is the exclusive element that owns chat scrolling.
    • Centralized Controller: All programmatic scrolls are routed through a single typed controller (useChatScrollController) using explicit reasons and priorities.
    • User Gesture Priority: Active user gestures take durable ownership of the scroll position until the user explicitly requests a navigation action or returns to the bottom.
    • Atomic Operations: The controller enforces one active operation and at most one physical write per animation frame.
    • Mode Gating: Passive scroll owners (like 'restore' or 'follow' modes) are gated; for example, 'follow' mode cannot run while in 'reading' mode.

  8. Understand the Memory Vector Store v2 Format

    dev

    DeepChat's Memory Vector Store v2 uses a plain DuckDB table with an exact brute-force scan instead of a persistent ANN (Approximate Nearest Neighbor) index. This design ensures crash consistency and exact recall results without the corruption risks associated with persistent HNSW indices.

    Key Characteristics

    • Storage Engine: Uses core DuckDB functions for vectorized exact scans (ORDER BY array_cosine_distance(...) LIMIT k).
    • Performance: Optimized for sub-millisecond queries at current scales (e.g., ~700k FLOPs for 344 rows at 1024-dim).
    • Crash Consistency: Uses standard DuckDB WAL replay, making it safe against unclean shutdowns.
    • No VSS Required: Unlike v1, v2 does not require the vss extension for standard create, open, or query operations.

  9. Understand the Light OCR Attachment Routing Architecture

    dev

    The Light OCR integration uses a multi-boundary architecture to handle image-to-text extraction offline. The key components are:

    1. AttachmentCapabilityRouter: Manages attachment policies and the three-state preparation results.
    2. ImageTextExtractionService: Implements ImageTextExtractionPort. It handles byte snapshotting, image preprocessing, extraction scheduling, text limits, and cache coordination.
    3. LightOcrProcessHost: Manages the standalone Node helper protocol, the engine lifecycle, and the runtime identity.
    4. OcrArtifactStore: Manages encrypted, machine-local derived artifacts and leases.
    5. OcrRuntimeAssetResolver: Resolves immutable bundled paths for assets (does not handle downloads/installation).

    Data flows from the renderer/remote input through a preflight check, model capability assessment, preprocessing, and finally through the OCR engine (or cache) to produce a resolved SendMessageInput.

  10. Understand the Plugins Hub Product Surface

    dev

    The /plugins route serves as the primary extension hub in DeepChat. It provides access to:

    • Official plugin detail routes
    • MCP (Model Context Protocol) management
    • Skills management
    • Remote management
    • ACP (Agent Client Protocol) availability status (shown as a boundary state)

    When interacting with the hub, the UI preserves standard navigation (back/refresh) and handles loading, empty, and error states. Plugin-specific settings are rendered via a Desktop-owned settings window rather than the plugin creating its own unmanaged window.

  11. Understand the DeepChat mental model and architecture

    dev

    DeepChat follows a specific data and execution flow from the UI to the main process:

    Vue component / Pinia store $\rightarrow$ src/renderer/api/*Client $\rightarrow$ window.deepchat $\rightarrow$ src/shared/contracts/routes + events $\rightarrow$ module routes $\rightarrow$ owning main module.

    The main process uses a single composition root located at src/main/app/composition.ts. This root is responsible for creating modules, injecting dependencies, registering routes, and managing start/stop lifecycles. It does not provide a module lookup entry point to business logic.

    Note: Do not use legacy components such as src/main/presenter/, global Presenter, LifecycleManager, EventBus, useLegacyPresenter(), or src/renderer/api/legacy/** as they have been removed.

  12. Understand the Cache-Aware Context Runtime Architecture

    dev

    The Cache-Aware Context Runtime is designed to optimize AI provider requests by utilizing prompt caching while maintaining a deterministic, stable prefix. It separates 'deterministic' instructions (system prompts) from 'untrusted' mutable content (summaries, handoff state, and Memory) to ensure that repeated turns with unchanged resources produce a byte-identical stable prefix, maximizing cache hits.

    Key architectural principles:

    • Tape as Source of Truth: Uses an append-only model for execution history.
    • Prompt Ordering: Follows a strict hierarchy to protect the stable prefix:
      1. Deterministic base system instructions.
      2. Synthetic user checkpoint (derived from summary/handoff state).
      3. Complete history turns.
      4. Active user turn (including untrusted Memory).
      5. Current user payload/assistant continuation.
    • Role Isolation: Summaries, reconstruction state, and Memory are never assigned the system role; they are treated as untrusted user-role contributions to prevent invalidating the provider's stable prefix.