@kleros/tg-extractor

Copies the Telegram chats a Kleros BD member chooses, verbatim, into the BD team's raw archive on a Google shared drive. It is the first step towards a shared CRM.

This tool is for Kleros BD members. It needs access to the BD shared drive, which holds the Kleros Telegram application details, so it won't work for anyone else.

Install

You need Node 22 or later. On macOS or Windows, you also need Drive for Desktop, signed in to your kleros.io account, with the BD shared drive visible and its tg-extractor folder made available offline. On Linux, use any client that syncs the shared drive to a local folder.

npm i -g @kleros/tg-extractor

The step-by-step guide is the runbook.

The control panel

Type tg-extractor with nothing after it. The control panel opens in your browser, and you do everything else by clicking: Set up, Choose chats, Import a Telegram folder, Export (with "dry run" and "gentle"), Status, Change folder, Log out of Telegram and Quit. Keep the terminal window open while you use it: closing it quits.

The control panel listens only on this computer, and refuses requests from other websites. Closing its tab never stops an export.

Commands

Each button runs one of these commands, which you can also type yourself. They refuse to start while the control panel is open.

| Command | What it does | |---|---| | tg-extractor setup | Logs in to your Telegram account by QR code, or by phone number and code. It finds the tg-extractor folder on the shared drive and keeps your login in the OS keyring. | | tg-extractor select | Adds, removes or lists the chats in your scope list, with fuzzy search. --import-folder <name> adds the chats of a Telegram folder. | | tg-extractor run | Exports the chats in your scope list to the raw archive. --dry-run only lists them. --gentle goes slower. | | tg-extractor status | Shows how up to date each chat in your scope list is. | | tg-extractor folder | Changes the raw archive folder, keeping your Telegram login. It warns first if the new folder holds none of your exported files. | | tg-extractor revoke | Logs the extractor out of Telegram and deletes its keyring entries. | | tg-extractor ui | Opens the control panel, as a bare tg-extractor does at a terminal on a computer with a display. |

What it never does

• It never sends, edits, deletes or reacts to messages. It never marks chats read, and never changes your folders, contacts or settings. Every Telegram call goes through an allowlist of read methods.
• It never exports a chat you haven't added to your scope list yourself.
• It never writes your Telegram login to a file. The login stays in the OS keyring.
• It never calls a Google API. It writes to the shared drive as a local folder.

More

• Changelog
• Project README: how it works, the archive format and design decisions
• Issues

MIT licensed.