SkillFoxx

Type a name, a task or a service

Telegram Search

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

Skill

Medium risk

We rate an entry medium when the tool runs code, makes network calls or reads project files. Check what exactly it does before installing.

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

In your terminal, with SkillFoxx CLI

npx skillfoxx add skills/telegram-search

Detects the agents on your machine, checks the risk and pins the version.

Other ways to install

Run in a terminal in the project folder

npx skills add groupultra/telegram-search --skill telegram-search-cli -a claude-code -y

The skills tool installs the current version from the repository. Add the -g flag to use the skill in every project.

Without third-party tools, from commit 5d73488
tmp=$(mktemp -d)
git clone --filter=blob:none --no-checkout https://github.com/groupultra/telegram-search.git "$tmp"
git -C "$tmp" sparse-checkout set --no-cone /.agents/skills/telegram-search-cli/
git -C "$tmp" checkout 5d734888401f0a63a86e3dd29f942a5275da0207
mkdir -p .claude/skills
cp -R "$tmp/.agents/skills/telegram-search-cli" .claude/skills/telegram-search-cli

Commands for macOS and Linux, on Windows run them in Git Bash.

Run in a terminal in the project folder

npx skills add groupultra/telegram-search --skill telegram-search-cli -a cursor -y

The skills tool installs the current version from the repository. Add the -g flag to use the skill in every project.

Without third-party tools, from commit 5d73488
tmp=$(mktemp -d)
git clone --filter=blob:none --no-checkout https://github.com/groupultra/telegram-search.git "$tmp"
git -C "$tmp" sparse-checkout set --no-cone /.agents/skills/telegram-search-cli/
git -C "$tmp" checkout 5d734888401f0a63a86e3dd29f942a5275da0207
mkdir -p .agents/skills
cp -R "$tmp/.agents/skills/telegram-search-cli" .agents/skills/telegram-search-cli

Commands for macOS and Linux, on Windows run them in Git Bash.

Run in a terminal in the project folder

npx skills add groupultra/telegram-search --skill telegram-search-cli -a github-copilot -y

The skills tool installs the current version from the repository. Add the -g flag to use the skill in every project.

Without third-party tools, from commit 5d73488
tmp=$(mktemp -d)
git clone --filter=blob:none --no-checkout https://github.com/groupultra/telegram-search.git "$tmp"
git -C "$tmp" sparse-checkout set --no-cone /.agents/skills/telegram-search-cli/
git -C "$tmp" checkout 5d734888401f0a63a86e3dd29f942a5275da0207
mkdir -p .github/skills
cp -R "$tmp/.agents/skills/telegram-search-cli" .github/skills/telegram-search-cli

Commands for macOS and Linux, on Windows run them in Git Bash.

Run in a terminal in the project folder

npx skills add groupultra/telegram-search --skill telegram-search-cli -a codex -y

The skills tool installs the current version from the repository. Add the -g flag to use the skill in every project.

Without third-party tools, from commit 5d73488
tmp=$(mktemp -d)
git clone --filter=blob:none --no-checkout https://github.com/groupultra/telegram-search.git "$tmp"
git -C "$tmp" sparse-checkout set --no-cone /.agents/skills/telegram-search-cli/
git -C "$tmp" checkout 5d734888401f0a63a86e3dd29f942a5275da0207
mkdir -p .agents/skills
cp -R "$tmp/.agents/skills/telegram-search-cli" .agents/skills/telegram-search-cli

Commands for macOS and Linux, on Windows run them in Git Bash.

Run in a terminal in the project folder

npx skills add groupultra/telegram-search --skill telegram-search-cli -a gemini-cli -y

The skills tool installs the current version from the repository. Add the -g flag to use the skill in every project.

Without third-party tools, from commit 5d73488
tmp=$(mktemp -d)
git clone --filter=blob:none --no-checkout https://github.com/groupultra/telegram-search.git "$tmp"
git -C "$tmp" sparse-checkout set --no-cone /.agents/skills/telegram-search-cli/
git -C "$tmp" checkout 5d734888401f0a63a86e3dd29f942a5275da0207
mkdir -p .agents/skills
cp -R "$tmp/.agents/skills/telegram-search-cli" .agents/skills/telegram-search-cli

Commands for macOS and Linux, on Windows run them in Git Bash.

Run in a terminal in the project folder

tmp=$(mktemp -d)
git clone --filter=blob:none --no-checkout https://github.com/groupultra/telegram-search.git "$tmp"
git -C "$tmp" sparse-checkout set --no-cone /.agents/skills/telegram-search-cli/
git -C "$tmp" checkout 5d734888401f0a63a86e3dd29f942a5275da0207
mkdir -p .devin/skills
cp -R "$tmp/.agents/skills/telegram-search-cli" .devin/skills/telegram-search-cli

Commands for macOS and Linux, on Windows run them in Git Bash.

Formerly Windsurf.

Run in a terminal in the project folder

npx skills add groupultra/telegram-search --skill telegram-search-cli -a cline -y

The skills tool installs the current version from the repository. Add the -g flag to use the skill in every project.

Without third-party tools, from commit 5d73488
tmp=$(mktemp -d)
git clone --filter=blob:none --no-checkout https://github.com/groupultra/telegram-search.git "$tmp"
git -C "$tmp" sparse-checkout set --no-cone /.agents/skills/telegram-search-cli/
git -C "$tmp" checkout 5d734888401f0a63a86e3dd29f942a5275da0207
mkdir -p .cline/skills
cp -R "$tmp/.agents/skills/telegram-search-cli" .cline/skills/telegram-search-cli

Commands for macOS and Linux, on Windows run them in Git Bash.

Run in a terminal in the project folder

npx skills add groupultra/telegram-search --skill telegram-search-cli -a roo -y

The skills tool installs the current version from the repository. Add the -g flag to use the skill in every project.

Without third-party tools, from commit 5d73488
tmp=$(mktemp -d)
git clone --filter=blob:none --no-checkout https://github.com/groupultra/telegram-search.git "$tmp"
git -C "$tmp" sparse-checkout set --no-cone /.agents/skills/telegram-search-cli/
git -C "$tmp" checkout 5d734888401f0a63a86e3dd29f942a5275da0207
mkdir -p .roo/skills
cp -R "$tmp/.agents/skills/telegram-search-cli" .roo/skills/telegram-search-cli

Commands for macOS and Linux, on Windows run them in Git Bash.

A fork of Roo Code, same .roo folders.

Run in a terminal in the project folder

npx skills add groupultra/telegram-search --skill telegram-search-cli -a opencode -y

The skills tool installs the current version from the repository. Add the -g flag to use the skill in every project.

Without third-party tools, from commit 5d73488
tmp=$(mktemp -d)
git clone --filter=blob:none --no-checkout https://github.com/groupultra/telegram-search.git "$tmp"
git -C "$tmp" sparse-checkout set --no-cone /.agents/skills/telegram-search-cli/
git -C "$tmp" checkout 5d734888401f0a63a86e3dd29f942a5275da0207
mkdir -p .agents/skills
cp -R "$tmp/.agents/skills/telegram-search-cli" .agents/skills/telegram-search-cli

Commands for macOS and Linux, on Windows run them in Git Bash.

Run in a terminal in the project folder

tmp=$(mktemp -d)
git clone --filter=blob:none --no-checkout https://github.com/groupultra/telegram-search.git "$tmp"
git -C "$tmp" sparse-checkout set --no-cone /.agents/skills/telegram-search-cli/
git -C "$tmp" checkout 5d734888401f0a63a86e3dd29f942a5275da0207
mkdir -p .agents/skills
cp -R "$tmp/.agents/skills/telegram-search-cli" .agents/skills/telegram-search-cli

Commands for macOS and Linux, on Windows run them in Git Bash.

Run in a terminal in the project folder

tmp=$(mktemp -d)
git clone --filter=blob:none --no-checkout https://github.com/groupultra/telegram-search.git "$tmp"
git -C "$tmp" sparse-checkout set --no-cone /.agents/skills/telegram-search-cli/
git -C "$tmp" checkout 5d734888401f0a63a86e3dd29f942a5275da0207
mkdir -p .agents/skills
cp -R "$tmp/.agents/skills/telegram-search-cli" .agents/skills/telegram-search-cli

Commands for macOS and Linux, on Windows run them in Git Bash.

You will need: Node.js

Checked against the repository on Sep 25, 2026, commit 5d73488.

Text for your agent

Build the CLI: git clone https://github.com/groupultra/telegram-search.git && cd telegram-search && pnpm install && cp .env.example .env, then pnpm -F @tg-search/cli build. The skill lives in .agents/skills/telegram-search-cli; commands start with pnpm cli --profile=<profile> ...

Other ways from the author
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.

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.

Security check

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

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.

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.

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.

Official

A self-hosted knowledge base with block-level references and a built-in MCP server for connecting AI agents to your notes

MCP serverMedium risk46.5K
Editors’ pick

A CLI for every Google Workspace API with JSON output and agent skills: Drive, Gmail, Calendar, Sheets and more

CLIHigh risk31.2K
Editors’ pick

Local search over Markdown notes, docs and meeting transcripts: keywords, semantic search and reranking, with an MCP server

CLIMedium riskNo VPN needed30.1K
Editors’ pick

A task manager for AI-driven development: breaks a PRD into dependent tasks and guides the agent through them via MCP or CLI

MCP serverMedium risk28.1K
Foxx AITelegram Search

I am Foxx AI and I have already vetted this tool. Ask about install, setup or anything else, and I will keep it simple.