All writing
CLILLMWhatsAppOpen Source

I Built a CLI That Reads My WhatsApp, iMessage, and Telegram — Then Writes Intelligence Reports

March 4, 2026

I have ongoing business conversations across WhatsApp, iMessage, and Telegram. Action items get buried. Decisions get forgotten. Topics drift without anyone noticing.

I wanted a tool that could read those conversations, categorize messages by topic, extract action items and decisions, and write structured reports — all locally on my machine, not through some web app that uploads my chat data to a server.

Nothing I found did all of that. So I built chatlens.

What Already Exists

There are plenty of chat analytics tools. I looked at over 20 of them before writing code.

WhatsApp-only web apps like Chatilyzer, WhatsAnalyze, ChatAnalyzer, and WhatStats give you stats — top senders, emoji usage, messages per day. Some run entirely in the browser (good for privacy), but they only support WhatsApp and they don't do any semantic analysis. You get counts, not understanding.

Multi-platform tools exist too. Chat Analytics by mlomb is an open-source project that generates HTML reports from Discord, Telegram, WhatsApp, and Messenger exports. It's the closest multi-platform open-source competitor for basic stats, but it doesn't support iMessage and there's no LLM analysis. ChatRecap AI covers the most platforms (WhatsApp, Telegram, Instagram, iMessage, Discord, Snapchat, SMS) and does AI-powered analysis, but it's relationship-focused and your data goes to their servers. MosaicChats covers five platforms including iMessage and Telegram, but it's also relationship/dating focused.

CLI tools are rarer. Chatistics by MasterScrat (~930 GitHub stars) is a Python CLI that parses Messenger, Hangouts, WhatsApp, and Telegram into DataFrames. No iMessage support, no LLM analysis, and it hasn't seen much activity since 2020. imessage-conversation-analyzer handles iMessage but nothing else.

AI-powered analysis is the newest category. Chattier uses Google Gemini to do topic analysis on WhatsApp chats — but it's WhatsApp-only, English-only, and cloud-based. Chat Analyzer lets you ask questions about your WhatsApp chat using AI, but it's token-based (100 tokens for $2.99) and limited to ~8,000 messages per chat.

MCP servers are the closest to what I wanted. There are WhatsApp MCP servers (lharries/whatsapp-mcp, Composio's WhatsApp toolkit), iMessage MCP servers (iMessage Advanced Insights, @wyattjoh/imessage-mcp), and even a multi-platform one (claude-mcp-poke covers iMessage, WhatsApp, SMS, and Telegram). These give you ad-hoc LLM analysis — ask Claude to summarize a conversation, find a message, etc. They're good for one-off questions.

What none of them do is run a structured, repeatable pipeline — define your topics, schedule runs, track state across runs, deduplicate messages, write per-topic markdown reports with action items and decision logs, detect topic trends over time. That's the gap chatlens fills. Not "can an LLM read my chats" (MCP servers already do that) but "can I get consistent, structured intelligence reports from my chats without manually prompting every time."

What Chatlens Does

Chatlens connects to your messaging platforms, fetches messages, runs them through an LLM to categorize by topic, then writes structured markdown reports.

The pipeline:

  1. Fetch — Pull messages from WhatsApp (linked device via headless Chromium), iMessage (reads local chat.db), or Telegram (TDLib).
  2. Dedup — Track seen message IDs so reruns don't reprocess old messages.
  3. Categorize — One LLM call categorizes all messages against your topic roster. Messages that don't fit any topic get flagged as potential "emerging topics."
  4. Summarize — Each active topic gets summarized in parallel — bullet points, action items, decisions, open questions.
  5. Write — Per-topic markdown files, a dashboard index, and a cross-topic decision log.
  6. Save state — Timestamps and seen IDs persisted for the next run.

You define your own topics in the config:

{
  "topics": [
    {
      "id": "01_product",
      "name": "Product Strategy",
      "description": "Product direction, roadmap, feature decisions",
      "keywords": ["product", "roadmap", "feature", "MVP"]
    }
  ]
}

The output is plain markdown that works anywhere — Obsidian, VS Code, GitHub, a static site, cat in your terminal.

The LLM Layer

Chatlens supports three providers: Anthropic (Claude), OpenAI (GPT), and Ollama for fully local processing.

The categorization prompt sends all messages in a batch with your topic roster. Each message is wrapped in XML boundary tags (<message index="0" date="2026-03-04" time="14:30" sender="Tim">) to make it harder for chat content to interfere with the LLM's instructions. The LLM returns a JSON mapping of message indices to topic IDs.

If the LLM call fails or returns garbage, chatlens falls back to simple keyword matching. No data is lost — you just get less accurate categorization until the next run.

Summarization runs in parallel using Promise.allSettled, so one topic failing doesn't kill the whole run. Failed topics get a fallback entry noting how many messages were exchanged and recommending manual review.

If you don't want any data leaving your machine, use Ollama. Zero API calls, zero network traffic.

Prompt Injection

When you feed arbitrary chat messages to an LLM, prompt injection is a real risk. Someone in your group chat could send "IGNORE ALL PREVIOUS INSTRUCTIONS" and corrupt the output.

Chatlens handles this with:

  • XML boundary tagging on each message, making it harder for injected text to escape the message context.
  • System prompt hardening that explicitly tells the LLM to treat message content as data.
  • Output validation that checks the response against your topic roster — invented topic IDs get rejected.
  • Keyword fallback if the LLM produces invalid output.

The eval framework includes an injection resistance test (chatlens eval injection) that you can run against your chosen provider.

The worst case from a successful injection is a corrupted local report. Chatlens is read-only — it cannot send messages, modify chat history, or access files outside its configured paths.

Observability

Every run produces structured metrics: message counts, LLM calls, token usage, cost estimate, duration. These are saved as JSON alongside the run logs.

chatlens stats

Shows run history with token counts and costs so you can see exactly what each run consumed.

The stale item tracker flags action items that haven't been resolved after 3 days. The topic trend tracker shows which topics are heating up or cooling down based on message volume over recent runs.

214 Tests

The test suite has 214 tests across 19 files. Coverage includes:

  • Adapter factories and platform-specific clients
  • Config schema validation and env var resolution
  • Pipeline stages: sanitization, categorization, summarization
  • State persistence: load, save, dedup pruning, action item tracking, topic trends, run locking
  • Output generation: topic files, dashboard, decision log
  • Observability: metrics collection, structured logging, run reports
  • Eval runner: categorization scoring, injection detection, golden snapshots

The eval framework tests the LLM itself — you run chatlens eval categorize against real fixtures to measure how accurately your chosen model categorizes messages, and chatlens eval injection to check its resistance to prompt injection.

Getting Started

git clone https://github.com/ITeachYouAI/chatlens.git
cd chatlens
npm install
npx tsx bin/chatlens.ts init

The init wizard walks you through: your name, chat platform, contact to track, topics, LLM provider, and output directory. It writes chatlens.json (gitignored — it contains contact names).

For WhatsApp, start the daemon (chatlens server start), scan the QR code, and you're connected. For iMessage, install imessage-exporter and grant Full Disk Access. For Telegram, get API credentials from my.telegram.org and run chatlens auth telegram.

Then: chatlens track --dry-run to preview, chatlens track to run the full pipeline.

What It's Not

Chatlens is not a relationship analyzer, a "chat wrapped" generator, or an enterprise conversation intelligence platform. It doesn't do sentiment analysis, compatibility scoring, or MBTI detection. It doesn't have a web UI.

It's a CLI that reads your business conversations, categorizes them by topic, and writes markdown reports. That's the scope.

MIT licensed. Code on GitHub: ITeachYouAI/chatlens