octogram 🐙

A tiny, read-only Telegram client for AI agents.

octogram lets an AI assistant (like Claude) read your Telegram for you: list your chats, read messages, export history, and — the headline feature — transcribe and summarize any video or voice message, or answer questions about it.

It cannot send messages, reply, react, join, leave, delete, or change anything. Not "won't" — can't. There is no code in this repo that writes to Telegram. That's the whole point: you (or your own AI) can read all ~500 lines and confirm it in a few minutes.

---

Кратко по-русски

octogram — это маленький инструмент, который только читает твою телегу. Он умеет:

• показать список твоих чатов;
• прочитать сообщения из чата;
• расшифровать любое видео или голосовое из чата и сделать сводку, или ответить на твой вопрос по нему;
• выгрузить историю чата в файл.

Он физически не может ничего написать, ответить, поставить реакцию, вступить или удалить — в коде просто нет таких команд. Твой Клод может открыть эти файлы и убедиться сам. Настройка — ниже (Setup), там же по-английски, но шаги простые; попроси своего Клода пройти их вместе с тобой.

---

Why it's safe

• Read-only by construction. The tool exposes exactly these commands: login, check, dialogs, find, read, export, transcribe. Every one only reads. There is no send, reply, react, join, delete — no write API call anywhere.
• Everything stays on your machine. Your login (the .session file) and your credentials (.env) never leave your computer and are gitignored. octogram talks only to Telegram (to read) and, if you use it, to Google Gemini (to transcribe the one media file you asked about). Nothing else.
• No servers, no telemetry, no accounts. It's a local CLI. Nobody but you can see what you read.
• Small and auditable. ~500 lines of plain Python across 4 files. Ask your AI: "read every file in this repo and confirm it can only read Telegram, never write."

How to verify it yourself (or have your AI do it)

# Show every place the code calls Telegram. You'll see only read methods
# (iter_dialogs, get_entity, iter_messages, get_messages, download_media) —
# never send_message / send_file / SendReaction / delete / etc.
grep -rn "client\.\|\.send\|\.delete\|Request(" main.py transcribe.py config.py safety.py

---

Setup

You need Python 3.10+.

Site: https://octogram.marshub.uz

git clone https://git.marshub.uz/ruslan/octogram.git
cd octogram
cp .env.example .env        # then edit .env (see below)
./og login                  # first run auto-creates the venv, then logs you in

Fill in .env:

1. Telegram credentials — get your own (free, ~2 min): open my.telegram.org, log in with your phone → API development tools → create an app → copy api_id and api_hash into .env.
2. Gemini key (for transcription) — free at aistudio.google.com/apikey. Put it in .env. (Skip this if you'll only use offline transcription — see --local below.)

Then ./og login walks you through the phone/code/2FA prompts once. Done.

---

Usage

./og check                              # who am I logged in as? is config OK?
./og dialogs                            # list recent chats
./og find "mom"                         # find a chat/user by name or @username
./og read "family" --limit 30          # read last 30 messages of a chat
./og read 123456789 --full             # read by numeric id, full message text
./og export "work" --since 2026-06-01  # dump history to JSONL (redirect to a file)

# The headline feature — transcribe & summarize video/voice:
./og transcribe "lectures"                       # newest video/voice in that chat
./og transcribe "lectures" 4821                  # a specific message (by id)
./og transcribe "lectures" --ask "what's the deadline they mention?"
./og transcribe "lectures" --local               # offline Whisper, nothing sent to Google

<chat> can be a numeric id, an @username, or part of the chat's name.

Offline transcription

--local uses faster-whisper — fully offline, nothing leaves your machine. Install it once:

venv/bin/pip install faster-whisper

(If you also have a Gemini key, --local transcribes locally and only sends the resulting text to Gemini for a summary. With no key, you just get the transcript.)

---

Kill switch

touch /tmp/octogram_kill blocks every command instantly. rm /tmp/octogram_kill resumes. (There's also gentle rate-limiting so an AI in a loop can't hammer Telegram.)

---

What this is a fork of

octogram is the stripped-down, read-only, open-source cousin of a fuller private Telegram automation CLI. Everything that writes, everything project-specific, and all the heavy machinery (a full local mirror, a web client) was removed on purpose. What's left is the safe, understandable core you'd hand to a friend.

MIT licensed. Use it, read it, fork it.