SkillFoxx

Telegram Search skill

A skill and CLI for exporting and fuzzy-searching Telegram chat history: local database, vector search, read-only

  • 4,150 ★ on the repository
  • Last commit
  • AGPL-3.0
Skill

Extended access

Why this level

  • Works with private conversations through an authorized Telegram session
  • Bulk history export needs account access via Telegram Takeout
All reasons and checks

groupultra/telegram-searchAuthor:groupultra

Install

Services

Manual install

git clone https://github.com/groupultra/telegram-search.git
cd telegram-search
pnpm install
cp .env.example .env
pnpm run dev

Browser-only mode for local development.

Access and checks

How we review

Extended accessThe tool runs code or makes network calls and only reads external data.

  • Works with private conversations through an authorized Telegram session
  • Bulk history export needs account access via Telegram Takeout

This is third-party code. Review the repository files before installing.

What it does

Telegram Search gives an agent the tg-search CLI to work with Telegram chat history through an authorized local profile. It can list chats and read a bounded message range without persistence, and after explicit user consent it syncs history via Telegram Takeout into a local database with full-text and vector search, including semantic image search. From there the agent queries, searches and pulls message context locally, with no calls to Telegram, and can export history to deterministic JSONL. The skill explicitly forbids sending or modifying messages and requesting secrets like login codes or 2FA passwords.

Who it is for. For anyone who needs to quickly find old messages in large Telegram chats, including cross-language and meaning-based search, not just exact keyword matches.

Good fit when

  • You need to find a message by meaning rather than exact wording in a large chat
  • You need a summary of unread messages or an answer based on chat history
  • You need an exported archive of the conversation in a structured format

Not a fit when

  • You need to send or modify messages: the skill is read-only
  • You are not ready to explicitly confirm the chats, range and data scope for Telegram Takeout

Example request

Find every message about postponing the release in our team chat over the last month and show the context

Limitations

Bulk history sync goes through the official Telegram Takeout mechanism and requires authorizing the data export request on one of your Telegram devices, so it is not instant. It needs a locally running service (PGlite or PostgreSQL, optionally MinIO for media).

How to disable. Stop the service (docker compose down), remove the CLI profile, and delete the telegram-search-cli skill from your agent's skills directory.

FAQ

Could the agent accidentally send a message?

No, the skill explicitly forbids sending or modifying Telegram messages; it is a read-only tool.

Does every sync need confirmation?

Yes, bulk sync via Takeout only runs after explicit user approval of specific chats and a range, and needs confirmation on a Telegram device.

Discussion

No questions or reviews yet.

All Telegram tools

TG Telegram Parser refreshes a saved channel export, adding new posts and revisiting a configured number of earlier discussions.

CLIExtended access241

BotHelp analytics skill

claude-skill-bothelp

Russian stack

A Claude Code skill for the BotHelp Open API: a bot map, step-by-step drop-off, subscriber export and limited management via the open API

SkillExtended access

Telegram API MCP

telegram-api-mcp

Russian stack

MCP server for the Telegram Bot API: messages, channels, forums, payments and long posts from a bot, with Telegram rate limits built in

MCP serverBroad access34

A Telegram bot for OpenCode: send coding tasks, watch progress and switch models from your phone while OpenCode keeps running on your own computer

CLIBroad access1.4K

MCP Telegram with write access: the agent sends, edits and deletes messages, searches chats, keeps drafts and downloads media in your account over MTProto

MCP serverBroad access252

MCP Telegram for reading: the agent gets your account's dialog list and unread messages over MTProto and has no way to write on your behalf

MCP serverBroad access190

README in short

The main README, in Chinese, presents the product as a way to back up and find Telegram messages with local tokenization and vector search, including image search and smart unread summaries. There is a hosted demo, a server Docker image, and dev modes for browser-only or server with PGlite/PostgreSQL and MinIO. A separate English SKILL.md for agents sets hard contracts: bounded remote reads with no persistence, sync only after user consent, and a ban on sending messages or requesting secrets. AGPL-3.0 licensed.

README badge

Original SKILL.md

---
name: telegram-search-cli
description: Operate the Telegram Search CLI through an authorized local profile. Use when an agent needs to discover Telegram chats, read bounded remote messages, explicitly synchronize history with user-approved Telegram Takeout, query/search/contextualize persisted messages, compute statistics, export deterministic JSONL, or run a real CLI end-to-end canary. Never send or modify Telegram messages.
---

# Telegram Search CLI

Use the CLI as a local-first data tool. Let the agent compose atomic commands; do not require the web UI or a daemon.

## Contracts

- Treat stdout as exactly one JSON envelope. Read diagnostics, prompts, migration output, and progress from stderr.
- Use `chats list` and `messages list` for bounded remote reads without persistence.
- Use local `messages query`, `search`, `context`, `stats`, and `export` without connecting to Telegram.
- Use `sync --takeout` for message persistence and bulk history. Add `--takeout` only after the user explicitly approves the selected chats, time range, and data scope.
- Never send messages or modify Telegram data.

Report a problem