Telegram ReaderSAFE

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

# Choose finance-social-readers when prompted.
npx plugins add himself65/finance-skills

# Or install just this skill
npx skills add himself65/finance-skills --skill telegram-reader

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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)

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)**

```bash
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**

```bash
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:

```bash
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:

```bash
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

```bash
# 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):

```bash
# 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 is more reliable than parsing stdout
4. **Start with small exports** — use `-T last -i 20` unless the user asks for more
5. **Use filters on `chat ls`** to help users find the right channel before exporting
6. **Read-only** — don't send messages, join or lea

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (2)

| `--proxy PROXY` | Set proxy (e.g., `socks5://127.0.0.1:1080`, `http://127.0.0.1:7890`) |

| macOS / Linux | `curl -sSL https://docs.iyear.me/tdl/install.sh \| sudo bash` |

Gates applied: no_behavioural_pass.