WireCatLabs/tg-cli

Your whole Telegram account in the terminal, searchable on your computer, and ready for Claude Code,
Codex, Cursor or any agent — within limits you set.
Docs ·
Examples ·
WireCat
An example conversation (invented people, illustrative output):
Quick start
Allow about five minutes. tg personal setup registers your own Telegram app at
my.telegram.org, logs in by QR code, checks your first chats and installs
the agent skill. Downloading older history is a separate step.
It needs **Node 22.16+ or 24+**, or **Bun**, on macOS, Linux or Windows. Try it without installing:
npx @wirecat/tg-cli --help.
More: installation guide · on wirecat.dev
What can you do?
**Catch up.** *"Use tg CLI. What came in since this morning, and who is waiting for my answer?"*
**Find anything.** *"Use tg CLI. When did we agree on the venue with Alice?"* — an answer with the date
and the message itself.
**Keep your promises.** *"Use tg CLI. What did I promise, and what am I still waiting on?"* tg personal review
hands over everything said since the last review in one call, your own messages too.
**Run your groups.** *"Use tg CLI. Which questions in Hiking has nobody answered?"*
More: recipes, with a schedule and limits for each · on wirecat.dev
Built for AI agents
Your agent. Your Telegram. Your rules.
- **Agents with a terminal** (for example Claude Code, Codex, Gemini CLI) run tg commands
themselves. The bundled skill
tells them how: tg personal setup --agent … or tg skill install puts it in place, and tg skill show
prints it before login.
- **Apps without a terminal** (for example Claude Desktop, Cursor and other MCP clients) connect to
tg personal mcp. It comes with ready prompts: /catch-up, /review, /reply and /find.
More: the MCP server · on wirecat.dev
Why tg?
- **Your whole account, not only bots.** Every chat, group, channel and contact, with its history —
tg is one more of your devices.
- **Local-first search.** Everything read is kept on your computer. Search is fast, and --offline
answers without connecting.
- **Made for agents.** One operation per call, the same JSON shape every time with --json, a fixed
exit code for each kind of failure, an MCP server and a skill.
- **Safe by default.** Reading marks nothing read. A profile decides which actions an agent may take,
which chats it may send to, and how many messages an hour (30 by default). When a send's outcome is
unknown, tg says so and gives a repeat command that Telegram does not deliver twice.
- **The full Bot API too.** All 185 methods, next to the convenient bot commands.
More: compared with other tools · on wirecat.dev
Your account
tg works in your name, as one more of your devices. It is not a bot: it talks to Telegram over
MTProto, Telegram's own API for client apps, with an app you register yourself. It sees your chats,
their history, groups, channels and contacts.
- **Read.** Chats, history, one message with its neighbours, other people's unread messages in every
chat (tg personal inbox), everything since the last review (tg personal review), new messages as they arrive
(tg personal watch), a message's files, voice messages as text.
- **Write.** Markdown, replies, files, photos, videos and voice messages, silent and scheduled messages
(they go out even with this computer off), edits, forwards, pins, reactions, polls, deletion — for
you or for everyone.
- **Voice on your computer.** Telegram transcribes for Premium accounts; tg can also run a speech
model on this machine, downloaded only when you ask.
- **Contacts and the account.** Add, rename, block and import contacts; your own aliases and notes
for people; who you are logged in as, and every device logged in to the account.
- **One person.** Their profile, when they were last seen, their messages per shared chat, and whether
the account looks like a bot or a spammer.
More: using tg · on wirecat.dev · one person · on wirecat.dev
Log in and profiles