ChatLab

ChatLab is an open-source desktop app for understanding your social conversations. It combines a flexible SQL engine with AI agents so you can explore patterns, ask better questions, and extract insights from chat data, all on your own machine.

Currently supported: WhatsApp, LINE, QQ, Discord, Instagram, Telegram, iMessage, and Google Chat. Coming next: Messenger and KakaoTalk.

New install? Start here: Getting started

Core Features

• Built for large histories: Stream parsing and multi-worker processing keep imports and analysis responsive, even at million-message scale.
• Private by default: Your chat data and settings stay local. No mandatory cloud upload of raw conversations.
• AI that can actually operate on data: Agent + Function Calling workflows (24+ tools) can search, summarize, and analyze chat records with context.
• Insight-rich visual views: See trends, time patterns, interaction frequency, rankings, and more in one place.
• Cross-platform normalization: Different export formats are mapped into a unified model so you can analyze them consistently.

Installation

Desktop App

Download the installer for your OS from the official website or GitHub Releases, then double-click to install.

CLI

Requires Node.js ≥ 20.

npm i chatlab-cli -g

Start ChatLab:

clb web            # Start API + Web UI, auto-open in browser
clb web --no-open  # Start API + Web UI, skip auto-open
clb web --headless # API only, no Web UI (for scripts / AI Agents)

Common options: --port <port> (default 3110), --host <address>, --token <token>.

To run as a persistent background service (auto-start on login + auto-restart on crash):

clb web --daemon   # Install as system service (macOS / Linux)
clb status           # Check service status
clb stop             # Stop and uninstall service

For a full walkthrough, see the Quick Start guide.

Usage Guides

• Download Guide
• Chat Record Export Guide
• Standardized Format Specification
• Troubleshooting Guide

Preview

For more previews, please visit the official website: chatlab.fun

Architecture Overview

ChatLab is a pnpm monorepo built on Electron + Vue 3 + Nuxt UI + Tailwind CSS. Core business logic lives in shared packages (@openchatlab/core, @openchatlab/node-runtime, @openchatlab/tools), consumed by both the desktop app and the CLI service — so they stay in sync.

Data flows in five stages: format detection → stream parsing → local persistence → SQL + AI query → visualization.

For a deep dive, see the architecture documentation.

Architecture Principles

• Local-first by default: Raw chat data, indexes, and settings remain on-device unless you explicitly choose otherwise.
• Streaming over buffering: Stream-first parsing and incremental processing keep large imports stable and memory-efficient.
• Composable intelligence: AI features are assembled through Agent + Tool Calling, not hard-coded into one model path.
• Schema-first evolution: Import, query, analysis, and visualization share a consistent data model that scales with new features.

Local Development

For complete contributor instructions, see the Development Guide.

Requirements

• Node.js >= 24 < 25
• pnpm >= 11 < 12

Setup

# Install dependencies
pnpm install

# Start dev mode — prompts you to choose which app to launch
pnpm dev

Or launch a specific target directly:

pnpm dev:desktop   # Electron desktop app
pnpm dev:cli-web   # CLI Web frontend + local server
pnpm dev:web-wasm  # Browser-only Web WASM
pnpm dev:serve     # CLI server only
pnpm docs:dev      # Docs site

If Electron encounters exceptions during startup, you can try using electron-fix:

npm install electron-fix -g
electron-fix start

Privacy Policy & User Agreement

Before using this software, please read the Privacy Policy & User Agreement.

Community

Please follow these principles before submitting a Pull Request:

• Obvious bug fixes can be submitted directly.
• For new features, please submit an Issue for discussion first; PRs submitted without prior discussion will be closed.
• Keep one PR focused on one task; if changes are extensive, consider splitting them into multiple independent PRs.
• For local setup, repository structure, checks, and AI collaboration notes, see the Development Guide.

Thanks to all contributors:

License

AGPL-3.0 License