<div align="center">

skill-telegram

The only Telegram skill your AI agent needs.

Read messages. Parse channels. Download voice notes. One session, zero bots.

</div>

Why

Your AI agent can't read your Telegram. It can't check what you saved, parse industry channels, or process voice messages you recorded on the go. This skill gives it direct access via the Telegram user API — the same way you use Telegram, not through a limited bot.

One session file. All your chats. JSON output that pipes into anything.

<div align="center"> <img src="assets/telegram-architecture.png" alt="skill-telegram architecture: Agent → Scripts → Telegram → JSON" width="800" /> </div>

What It Does

• Reads any chat — Saved Messages, DMs, groups, public channels → JSON lines
• Parses channels at scale — multiple channels, date filtering, sanitized output with anti-injection protection
• Downloads voice notes — audio files + metadata, ready for transcription
• Diagnostics built in — one command checks env vars, session, dependencies, connectivity
• Portable — works from any directory. Session auto-discovered or explicitly pointed to

Quick Install

Claude Code (recommended):

/plugin marketplace add awrshift/skill-telegram

Manual:

# Copy skill to your project
git clone https://github.com/awrshift/skill-telegram.git
cp -r skill-telegram .claude/skills/telegram

Setup (5 minutes)

Step 1: Get Telegram API credentials

1. Go to https://my.telegram.org/apps
2. Log in with your phone number
3. Create an app (any name/description)
4. Copy api_id and api_hash

Step 2: Configure environment

Add to your .env file:

TG_API_ID=12345678
TG_API_HASH=your_api_hash_here

Step 3: Install dependency

pip install telethon

Step 4: Authenticate

source .env && python3 .claude/./scripts/tg_setup.py --auth

Enter your phone number → receive code in Telegram → enter code. Done. Session file created automatically.

Step 5: Verify

source .env && python3 .claude/./scripts/tg_setup.py

All checks should show [ OK ].

Usage

Output Format

All scripts output JSON lines (one JSON object per line):

{"id": 265894, "date": "2026-03-19T09:42:48+00:00", "text": "Message content here", "has_voice": false, "has_photo": false}

Channel parser adds sanitization:

{"channel": "SEOBAZA", "id": 1546, "date": "2026-03-19T03:29:34+00:00", "text": "Original", "text_sanitized": "Cleaned", "links": ["https://..."], "hash": "64e9a72207ed56d4", "views": 1403}

Scripts

Total: 770 lines. No frameworks, no heavy dependencies. Just Telethon + stdlib.

Session Resolution

The skill finds your session file automatically:

1. --session /path/to/file (CLI flag, highest priority)
2. TG_SESSION env var
3. .claude/data/telegram/tg_session.session (project-level)
4. ~/.telegram/tg_session.session (global)

Security

• User API — you authenticate as yourself, not as a bot
• Session file = your identity — protect it like a password
• Read-only — this skill never sends messages
• Sanitization — channel parser strips zero-width chars, backtick injection, excessive emoji
• No data storage — outputs to stdout/file, no database, no cloud

Gotchas

• First auth is interactive — you need to enter phone + code once
• One session at a time — don't run two scripts with the same session simultaneously
• Rate limits — Telegram throttles heavy usage (auto-handled with delays)
• Voice download ≠ transcription — the skill downloads audio. Use Whisper/mlx-whisper for transcription
• User API ≠ Bot API — this uses your account, sees what you see

Works With

Part of the AWRSHIFT Ecosystem

• skill-awrshift — adaptive decision-making framework
• skill-brainstorm — 3-round Claude x Gemini adversarial brainstorm
• ClawClaw Soul — persistent identity protocol for AI agents

Contributing

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

License

MIT — see LICENSE for details.

<div align="center"> <em>Your agent. Your Telegram. No bots.</em> </div>