telegram personal
- Repo stars 0
- Author repo telegram-personal
- Domain
- Engineering
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @000alen · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# telegram-personal
Read-only access to a personal Telegram account via Telethon (MTProto API).
## Setup
One-time: `bash scripts/setup.sh` (installs Telethon, runs interactive auth).
Requires `api_id` + `api_hash` from https://my.telegram.org → API Development.
Credentials stored at `~/.config/telegram-personal/credentials.json` (mode 600).
Session file at `~/.config/telegram-personal/session.session`.
## CLI: `scripts/tg.py`
```bash
# List all conversations
tg dialogs [--limit N]
# Read messages from a chat (username, phone, or numeric ID)
tg read <chat> [--limit 20]
# Search across all chats (or one specific chat)
tg search "query" [--chat <name>] [--limit 20]
# Show unread DMs/groups with previews
tg unread [--limit 30]
# Download media from a message
tg download <chat> <msg_id> [-o dir]
# Export chat to markdown
tg export <chat> [--since 7d] [--limit 500] [-o file.md]
# Get info about a chat or yourself
tg info [chat]
```
## Chat identifiers
Any of: `@username`, `+phone`, numeric ID (from `tg dialogs`), or chat title.
## Safety
- **Read-only** — no send/delete commands
- Session file = full account access. Never expose it
- Telethon auto-handles FloodWait (sleeps on rate limits)
- Global search iterates dialogs (slower); prefer `--chat` when possible
## Integration with OpenClaw
From a skill or heartbeat, call via exec:
```bash
cd /path/to/telegram-personal && uv run tg search "keyword" --limit 10
cd /path/to/telegram-personal && uv run tg unread
```
Sections and files
Listed in source order.
sections -> Setup → CLI: scripts/tg.py → Chat identifiers → Safety → Integration with OpenClaw
terms -> Read-only · Read-only access to a personal Telegram account via Telethon (MTProto API). · One-time: bash scripts/setup.sh (installs Telethon, runs interactive auth). · Requires apiid + apihash from https://my.telegram.org → API Development. · Credentials stored at ~/.config/telegram-personal/credentials.json (mode 600). · Any of: @username, +phone, numeric ID (from tg dialogs), or chat title. · - Read-only — no send/delete commands - Session file = full account access.
files/cmd -> bash scripts/setup.sh · api_id · api_hash · ~/.config/telegram-personal/credentials.json · ~/.config/telegram-personal/session.session · scripts/tg.py · @username · +phone
body sha256 -> e16912ca4b1e
Setup
One-time:
bash scripts/setup.sh(installs Telethon, runs interactive auth). Requiresapi_id+api_hashfrom https://my.telegram.org → API Development. Credentials stored at~/.config/telegram-personal/credentials.json(mode 600). Session file at~/.config/telegram-personal/session.session.Chat identifiers
Any of:
@username,+phone, numeric ID (fromtg dialogs), or chat title.Safety
Read-only — no send/delete commands Session file = full account access. Never expose it Telethon auto-handles FloodWait (sleeps on rate limits) Global search iterates dialogs (slower); prefer
--chatwhen possibleIntegration with OpenClaw
From a skill or heartbeat, call via exec: