How to use the Telegram Archive Search agent skill (telecrawl)

What the telecrawl skill makes the agent do

A skill is a folder of instructions that an AI agent loads so it knows how to handle a particular kind of task. The telecrawl skill covers Telegram history questions. It tells the agent to check the local archive first and to use the Telegram apps only for live or current state.

With the skill and the telecrawl command-line tool available, the agent can list chats, read messages, search across chats, look up contacts and folders, and import fresh data from Telegram Desktop or the native macOS Telegram app. It also knows how to run encrypted backups of the archive to a git repository.

• List recent chats or unread chats
• Read messages in a chat, optionally limited by date
• Search messages across all chats or within one chat
• Look up contacts, folders and topics
• Import or refresh the archive from a local Telegram data source

Install the telecrawl skill

Download the skill ZIP from this page and unzip it. The skill folder contains a single file, SKILL.md. For a personal setup, place the unzipped folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/ (unzip here)
• Project: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills → upload

Install and check the telecrawl CLI

The skill only tells the agent how to use telecrawl. It does not install it. Make sure the telecrawl command-line tool is installed and on your PATH before you rely on the skill. The skill's source expects the command to be named telecrawl and the archive database to live at ~/.telecrawl/telecrawl.db.

Once it is installed, check the archive status. Empty counts mean no import has run on this machine, not that you have no Telegram data.

Import your Telegram data

Telecrawl imports from Telegram Desktop (its tdata folder) or the native macOS Telegram app (Postbox), and detects the source automatically. Run doctor first to confirm a source is readable. Imports merge into the existing archive by default.

Use the fetch-media option only if you also want to pull Telegram cloud media. The --restore option replaces the archive, so treat it as destructive and confirm before running it.

• telecrawl doctor checks that a Telegram data source is readable
• telecrawl import merges data from the detected local app
• telecrawl import --fetch-media also pulls cloud media
• --restore replaces the archive and is destructive

Trigger the skill with natural requests

You do not need special syntax. Ask a normal question about your Telegram history and the agent will use the skill when it fits. Be specific about the chat, person, topic or date range, since that lets the agent run a narrower query.

If the archive on your current machine is empty, the skill tells the agent to check status first and prefer the archive host over answering from an empty database.

• "Search my Telegram archive for the hotel booking details from March."
• "Show my unread Telegram chats."
• "Summarise what Sam and I agreed on in our Telegram chat since January."
• "Which Telegram folders do I have, and what is in the Work folder?"

Understand the queries the agent runs

All read commands accept a --json flag, which the agent uses so it can parse results. You can run these yourself to check what the agent sees. Chat IDs come from the chats command and are passed to messages, search and topics.

• chats --limit 20 and chats --unread
• messages --chat ID --limit 50 --after DATE
• search "query" with an optional --chat ID
• contacts, folders and topics --chat ID

Use the remote archive host and back up safely

The source notes that the populated archive currently lives on a host called clawmac, with roughly 200 chats, while local databases on other Macs may be empty. If you use this path, the agent queries the host over SSH. This requires SSH access to steipete@clawmac. Your own setup will need its own host, so treat the example as a pattern rather than something to copy.

For backups, telecrawl writes encrypted age shards to a git repository. Check backup status before pushing.

• Remote check: ssh with RequestTTY and RemoteCommand disabled, then run telecrawl --json status on the host
• Backup requires age encryption and a git repository