telegram-read

lycfyi's avatarfrom lycfyi

Read and search synced Telegram messages. Use when user asks about Telegram conversations, wants to see messages, or search for specific content.

⭐2stars🔀0forks📁View on GitHub🕐Updated Jan 9, 2026
[Communication Tools]

When & Why to Use This Skill

The telegram-read skill enables Claude to efficiently access, search, and retrieve information from locally synced Telegram messages. It solves the challenge of manual message hunting by allowing users to query chat histories, filter by date or topic, and extract specific data points from Telegram groups and channels directly through the AI agent, significantly enhancing productivity and information retrieval speed.

Use Cases

  • Search for specific project keywords or decisions across multiple Telegram groups to find historical context quickly.
  • Retrieve the latest messages from a specific group to get a summary of recent discussions and action items.
  • Filter chat history by a specific date to locate information shared during a particular event or meeting.
  • Extract structured JSON data from Telegram conversations for further analysis, reporting, or integration into other workflows.
nametelegram-read
description"Read and search synced Telegram messages. Use when user asks about Telegram conversations, wants to see messages, or search for specific content."

telegram-read

Read and search synced Telegram messages.

Trigger Phrases

  • "read Telegram messages"
  • "what's in the Telegram group"
  • "search Telegram for [keyword]"
  • "show Telegram messages"
  • "telegram read"

Description

This skill reads messages from locally synced Telegram data. It can show recent messages, search for keywords, or filter by date.

Usage

Read all messages from default group:

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py

Read from specific group:

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py --group 1234567890

Show last N messages:

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py --last 20

Search for keyword:

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py --search "meeting"

Filter by date:

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py --date 2026-01-06

Read specific topic:

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py --group 1234567890 --topic announcements

Output as JSON:

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_read.py --json

Output Format

Markdown Output (default)

# My Group

Group: My Group (1234567890)
Type: supergroup
Last synced: 2026-01-06T12:00:00Z

---

## 2026-01-06

### 10:30 AM - @alice (123456)
Hello everyone!

### 10:31 AM - @bob (789012)
↳ replying to @alice:
Hey Alice!

JSON Output (--json)

{
  "group_id": 1234567890,
  "topic": "general",
  "message_count": 50,
  "messages": [
    {
      "date": "2026-01-06",
      "time": "10:30 AM",
      "author": "@alice (123456)",
      "content": "Hello everyone!"
    }
  ]
}

Search Mode

When using --search, only messages containing the keyword are returned:

python telegram_read.py --search "Python"

Output:

Found 3 messages matching 'Python':

### 10:30 AM - @alice (123456)
I love Python programming!

----------------------------------------

### 2:15 PM - @charlie (456789)
Python is great for automation

----------------------------------------

Reading Tips

  1. Start with recent messages: Use --last 20 to see the latest activity
  2. Search specific topics: Combine --topic with --search for targeted searches
  3. Export for analysis: Use --json to get structured data for further processing

Prerequisites

You must sync messages before reading:

python plugins/telegram-agent/tools/telegram_sync.py --group 1234567890

Exit Codes

  • 0 - Success
  • 1 - No synced data found
  • 2 - Configuration error
  • telegram-sync - Sync messages from Telegram
  • telegram-list - List groups and topics
  • telegram-send - Send messages to Telegram