ChatLab: Local-First Chat History Analysis with SQL and an AI Agent

The problem ChatLab solves, and who actually has it

Chat exports are a format problem before they are an analysis problem. WhatsApp hands you a text file with its own date convention, Telegram hands you JSON, Discord hands you a package of channel JSON files, and LINE, QQ, Instagram, iMessage and Google Chat each do something different again. Anyone who has tried to answer a simple question across two of those exports knows the cost: you write a parser per platform, reconcile timestamps and sender identities by hand, and only then can you start counting anything.

ChatLab's answer is to normalize all of it into a single model. The README states the supported set plainly: WhatsApp, LINE, QQ, Discord, Instagram, Telegram, iMessage and Google Chat, with Messenger and KakaoTalk listed as coming next. That sentence is the whole product thesis. If your history lives in one of those eight, the import step is the part ChatLab does for you; everything after it is querying.

The intended user is someone with a personal or community archive large enough that manual reading has stopped working. A group chat with a million messages, a support channel you want to audit, a family thread spanning years. The README frames the app as being for "understanding your social conversations," and the million-message figure appears in the feature list as the scale the parser is built for. This is not a tool for reading one conversation you could scroll through in ten minutes.

Format detection, stream parsing, and the monorepo that keeps two apps honest

The README describes a five-stage pipeline: format detection, stream parsing, local persistence, SQL plus AI query, and visualization. Each stage is a boundary you can reason about. Detection decides which parser runs. Parsing is stream-first, which the architecture principles call out explicitly: "Streaming over buffering." That choice is what makes the million-message claim plausible rather than aspirational, since a buffered parse of a large export holds the whole file in memory before writing anything.

The codebase is a pnpm monorepo on Electron, Vue 3, Nuxt UI and Tailwind CSS. The interesting structural decision is that business logic lives in shared packages rather than in the desktop app: @openchatlab/core, @openchatlab/node-runtime and @openchatlab/tools. Both the Electron desktop app and the CLI service consume those packages, so a fix to the parser lands in both. That is a real constraint on contributors, not just an organizational preference: you cannot patch the CLI's behavior in isolation from the desktop app without breaking the shared contract.

The AI layer is assembled through Agent plus Function Calling rather than wired to one model path. The README puts the tool count at 24 or more, and describes them as able to "search, summarize, and analyze chat records with context." The schema-first principle ties this together: import, query, analysis and visualization all read the same data model, so adding a new visualization does not require a new import path. Whether that holds in practice depends on how strictly the shared packages enforce the schema, which the README does not detail.

Installing ChatLab and running your first SQL query over an export

There are two install paths. The desktop route is a download: the README points to the official website at chatlab.fun with a download query parameter, or to GitHub Releases, and says to double-click the installer for your OS. For the CLI route, the README states a requirement of Node.js 20 or higher, which is lower than the Node.js 24 to 25 range the repository's package.json declares for local development. Treat the CLI's stated requirement as the one that applies to installing the published package.

The global install is a single npm command:

npm i chatlab-cli -g

That puts a `clb` binary on your path. The default way to start the service is `clb web`, which starts the API and the Web UI and opens a browser. Three flags change that behavior, and the README documents all three:

clb web --no-open    # start API + Web UI, skip auto-open
clb web --headless   # API only, no Web UI (for scripts / AI Agents)
clb web --daemon     # install as a system service (macOS / Linux)

The default port is 3110, and `--port`, `--host` and `--token` are the documented common options. If you are running this on a machine others can reach, `--host` and `--token` are the two you want to think about before the first start, since the README does not describe any authentication beyond the token flag.

The daemon path has its own lifecycle commands. `clb web --daemon` installs the service and, per the README, auto-starts on login and auto-restarts on crash. You check it with `clb status` and remove it with `clb stop`, which the README says stops and uninstalls the service. Note that `clb stop` is not a pause: it uninstalls. That is a surprising default for anyone who expects stop to mean stop.

After the service is up, the workflow the README describes is import, then query. The export guide lives at docs.chatlab.fun/usage/how-to-export and the standardized format specification at docs.chatlab.fun/standard/chatlab-format. The README does not give a worked SQL example in the repository text, so the exact table names are something to read from the format specification rather than guess at.

Where ChatLab is the wrong tool

The first limitation is coverage. Eight platforms are supported and two more are announced, which means anyone whose history is in Messenger or KakaoTalk is waiting. If your archive is split across a supported platform and an unsupported one, you get a partial picture and no indication from the README of how partial.

The second is the AI dependency. ChatLab's agent layer is described as Agent plus Function Calling with 24 or more tools, but the README does not name a model provider or describe what happens when no provider is configured. The privacy framing is careful here: "No mandatory cloud upload of raw conversations." That phrasing leaves room for AI requests to leave the machine, and it should. An agent that calls a hosted model sends something to that model. If your threat model forbids any conversation content leaving the device, verify the provider configuration before importing anything, and read the Privacy Policy and User Agreement at src/assets/docs/agreement_en.md, which the README asks you to read before use.

The third is headless deployment. The CLI exists and has a --headless mode aimed at scripts and AI agents, but it requires Node.js 20 or higher. If your target is a minimal container or an environment where you cannot install a Node runtime, the desktop app is not an option either and the CLI is not either.

Finally, the README is silent on rollback. There is no documented way to undo an import, and no documented migration path if a future release changes the persistence schema. For a tool whose whole value is a durable local archive, that silence is worth taking seriously before you point it at your only copy of an export.

How ChatLab differs from a general-purpose AI chat client

The obvious comparison is a general AI chat assistant, and the difference is not the model. It is what the model can reach. A general chat client receives whatever you paste into it. ChatLab's agent operates through tool calls against a local SQL layer, so the questions it can answer are bounded by the schema rather than by your clipboard discipline. "How did message volume in this group change after March" is a query, not a prompt.

The second comparison is writing your own scripts. A Python script over a parsed export gives you full control and no dependency on someone else's schema. What it does not give you is the eight parsers, the stream-first handling for large files, or the visualization layer. If you only ever analyze one platform and your exports are small, a script is less machinery. The crossover point is roughly where you start caring about a second platform or where a single import stops fitting comfortably in memory.

The third comparison is a hosted analytics service. Those typically want the raw conversation uploaded, which is the exact thing ChatLab is built to avoid. That difference is the product, not a feature of it.

Maintenance, upgrade cost, and the AGPL-3.0 boundary

The repository is not archived. The last push was on 2026-08-28, and the most recent release listed is v0.37.0 on the same date, following v0.36.2 on 2026-08-20 and v0.36.1 on 2026-08-18. Three releases inside two weeks is a fast cadence, and the version in package.json is 0.37.1, one patch ahead of the newest tagged release. That pattern suggests the main branch moves slightly ahead of tags, which is normal but means building from source gives you something the releases do not.

The upgrade cost is concentrated in the import step. Because the schema is shared across import, query, analysis and visualization, a schema change touches all four. The README does not document a migration tool or a versioned format, so the practical advice is to keep your original export files. They are the thing you can always re-import. Anything you derive inside ChatLab is the thing you might lose.

On licensing: the project is AGPL-3.0. For individual use that is unremarkable. The part to think about is the shared packages. @openchatlab/core, @openchatlab/node-runtime and @openchatlab/tools are consumed by both the desktop app and the CLI, and if you build a service around them and expose it over a network, AGPL-3.0's network clause is the clause your legal reviewer will want to read. This is not legal advice; it is a pointer to which file matters. The LICENSE file is at the repository root.

Contributions have a stated gate: the README says new features need an Issue for discussion first, and that "PRs submitted without prior discussion will be closed." Obvious bug fixes are exempt. If you are planning to send a patch, that rule is the first thing to satisfy.

Editorial conclusion

Adopt ChatLab if you keep years of chat exports and want SQL over them without uploading raw conversations. Skip it if you need Messenger or KakaoTalk today (the README lists both as coming next), or if a headless server with no Node.js 20+ runtime is your only target. Verify three things first: that your platform's export format is among the eight currently supported, that your intended AI provider is reachable from your machine, and that AGPL-3.0 fits how you plan to distribute anything you build on the shared @openchatlab packages.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes