/telegram-reader

name: telegram-reader
description: >
  Read Telegram channels and groups for financial news and market research with the
  tdl CLI: list chats and channels, find a channel by name, and export recent messages
  or a date or ID range. Use this skill whenever the user wants to check their
  Telegram, see what's new in their channels, read or export messages from a news,
  crypto, or trading channel or group, or gather market news and signals posted on
  Telegram. Read-only: it cannot send messages or join or leave channels.

Telegram News Skill (Read-Only)

If your host has not already executed the shell probes below (for example, in Codex), run the commands inside the `!` wrappers with its shell tool before choosing a setup path. Use the actual output; if shell access is unavailable, report that limitation.

Reads Telegram channels and groups for financial news and market research using [tdl](https://github.com/iyear/tdl), a Telegram CLI tool.

**This skill is read-only.** It is designed for financial research: reading channel messages, monitoring financial news channels, and exporting message history. It does NOT support sending messages, joining/leaving channels, or any write operations.

---

Step 1: Ensure tdl Is Installed

**Current environment status:**

!`(command -v tdl && tdl version 2>&1 | head -3 || echo "TDL_NOT_INSTALLED") 2>/dev/null`

If the status above shows a version number, tdl is installed — skip to Step 2.

If `TDL_NOT_INSTALLED`, install tdl based on the user's platform:

| Platform | Install Command | |----------|----------------| | macOS / Linux | `curl -sSL https://docs.iyear.me/tdl/install.sh \| sudo bash` | | macOS (Homebrew) | `brew install telegram-downloader` | | Linux (Termux) | `pkg install tdl` | | Linux (AUR) | `yay -S tdl` | | Linux (Nix) | `nix-env -iA nixos.tdl` | | Go (any platform) | `go install github.com/iyear/tdl@latest` |

Default to Homebrew on macOS. On Linux the install script runs with `sudo`, so confirm with the user before using it, or offer their package manager instead.

---

Step 2: Ensure tdl Is Authenticated

**Current auth status:**

!`(tdl chat ls --limit 1 2>&1 >/dev/null && echo "AUTH_OK" || echo "AUTH_NEEDED") 2>/dev/null`

If `AUTH_OK`, skip to Step 3.

If `AUTH_NEEDED`, guide the user through login. **Login requires interactive input** — the user must enter their phone number and verification code manually.

Login methods

**Method A: QR Code (recommended — fastest)**

tdl login -T qr

A QR code will be displayed in the terminal. The user scans it with their Telegram mobile app (Settings > Devices > Link Desktop Device).

**Method B: Phone + Code**

tdl login -T code

The user enters their phone number, then the verification code sent to their Telegram app.

**Method C: Import from Telegram Desktop**

If the user has Telegram Desktop installed and logged in:

tdl login

This imports the session from the existing desktop client. The desktop client must be from the [official website](https://desktop.telegram.org/), NOT from the App Store or Microsoft Store.

Namespaces

By default, tdl uses a `default` namespace. To manage multiple accounts:

tdl login -n work -T qr      # Login to "work" namespace
tdl chat ls -n work           # Use "work" namespace for commands

Important login notes

• Login is a **one-time** operation. The session persists on disk after successful login.
• If login fails, ask the user to check their internet connection and try again.
• **Never ask for or handle Telegram passwords/2FA codes programmatically** — always let the user enter them interactively.

---

Step 3: Identify What the User Needs

Match the user's request to one of the read operations below.

| User Request | Command | Key Flags | |---|---|---| | List all chats/channels | `tdl chat ls` | `-o json`, `-f "FILTER"` | | List only channels | `tdl chat ls -f "Type contains 'channel'"` | `-o json` | | Export recent messages | `tdl chat export -c CHAT -T last -i N` | `--all`, `--with-content` | | Export messages by time range | `tdl chat export -c CHAT -T time -i START,END` | `--all`, `--with-content` | | Export messages by ID range | `tdl chat export -c CHAT -T id -i FROM,TO` | `--all`, `--with-content` | | Export from a topic/thread | `tdl chat export -c CHAT --topic TOPIC_ID` | `--all`, `--with-content` | | Search for a channel by name | `tdl chat ls -f "VisibleName contains 'NAME'"` | `-o json` |

Chat identifiers

The `-c` flag accepts multiple formats:

| Format | Example | |--------|---------| | Username (with @) | `-c @channel_name` | | Username (without @) | `-c channel_name` | | Numeric chat ID | `-c 123456789` | | Public link | `-c https://t.me/channel_name` | | Phone number | `-c "+1 123456789"` | | Saved Messages | `-c ""` (empty) |

---

Step 4: Execute the Command

Listing chats

# List all chats
tdl chat ls

# JSON output for processing
tdl chat ls -o json

# Filter for channels only
tdl chat ls -f "Type contains 'channel'"

# Search by name
tdl chat ls -f "VisibleName contains 'Bloomberg'"

Exporting messages

Always use `--all --with-content` to get text messages (not just media):

# Last 20 messages from a channel
tdl chat export -c @channel_name -T last -i 20 --all --with-content -o /tmp/tdl-export.json

# Messages from a time range (Unix timestamps)
tdl chat export -c @channel_name -T time -i 1710288000,1710374400 --all --with-content -o /tmp/tdl-export.json

# Messages by ID range
tdl chat export -c @channel_name -T id -i 100,200 --all --with-content -o /tmp/tdl-export.json

Key rules

1. **Check auth first** — run `tdl chat ls --limit 1` before other commands to verify the session is valid 2. **Always use `--all --with-content`** when exporting messages for reading — without these flags, tdl only exports media messages 3. **Use `-o FILE`** to save exports to a file, then read the JSON — this i