Skip to content

Home

Jump to bottom
github-actions[bot] edited this page Oct 17, 2026 · 1 revision

tg — Telegram CLI for AI agents

The full guide lives at wirecat.dev/en/docs/tg. These wiki pages copy the docs/ folder on every change to main, so an edit made here is overwritten. To fix a page, open a pull request against docs/.

Questions and ideas: Discussions. What changed in each version: releases. tg is part of WireCat.

tg connects your own Telegram account to the terminal and to your AI agent (for example Claude Code, Codex, Cursor or Gemini CLI). Use it when you want to read, search and answer your chats without opening the Telegram app, or hand that work to an agent within limits you set.

This page tells you what tg can do, how to start in about five minutes, and which page answers which question.

Three terms appear on every page:

  • Terminal (command line): the window where you type commands, such as Terminal on macOS or PowerShell on Windows. tg is one command you type there.
  • AI agent: a program that does tasks for you and can run commands, such as Claude Code or Codex. It uses tg for you.
  • Skill: a short instruction file that tells your agent how to use tg. Setup installs it.

What it can do

You want to Where
Read your chats and other people's unread messages; by default nothing is marked read Using tg
Find what was said, by words, people, dates, files or topic Search
Keep a copy of your messages on this computer, and search or export it The local store
Answer and send, yourself or through an agent, within the limits you set Using tg, Permissions
See which questions nobody answered in the groups you run, and who joined Groups you run
Run a Telegram bot from the terminal A Telegram bot
Use Telegram from an app with no terminal (for example Claude Desktop or Cursor) or from a chat in the browser The MCP server, ChatGPT, Codex or Claude in the browser

Every command does one thing, gives the same shape of answer every time, and has a fixed exit code for each kind of failure. This is why scripts and agents can rely on it.

Get started

npm install -g @wirecat/tg-cli
tg personal setup         # guided app registration, login and agent skill
tg personal inbox         # other people's unread messages, in every chat; nothing is marked read
tg personal messages list me  # Saved Messages, the latest 20

Allow about five minutes for setup. Downloading older chat history is a separate step. To choose the agent that gets the skill, add --agent with codex, cursor, claude, gemini or all (for example tg personal setup --agent codex). tg setup --help shows the login choices and the Windows instructions.

With a bot (support here is an example name of a bot profile):

tg support bot auth set                          # the token, typed without showing it
tg support bot api get-me --json

tg needs Node 22.16+ or 24+, or Bun (what to install first). The first login asks for your own Telegram app; tg can register it for you (your Telegram app).

How tg differs from other tools: compared with other tools.

Where to go next

Page Answers
Installation What does it need, where do its files go, how do I upgrade or remove it?
Using tg How do I read, page, send, and use it from a script?
Login, sessions and profiles How does login work, where are the keys, how do profiles work?
The local store What does the local store keep, and how do I fill, search, export and back it up?
Groups you run How do I keep up with a group I run?
A Telegram bot How do I run a Telegram bot from the command line?
The MCP server How do I connect Claude Desktop, Cursor or another client without a terminal?
ChatGPT, Codex or Claude in the browser How do I reach it from ChatGPT or Claude in the browser?
Recipes What can an agent do for me every day, and how do I run it on a schedule?
All commands Every command, option and exit code
Configuration What can I set, and which value wins?
Diagnostics: what a command did What did a command do, and what is never recorded?
Troubleshooting Something does not work: what the screen says, and what to do
Security What reaches the disk and the network, and what stops a send going to the wrong place?
Roadmap What is coming next?

Search: tg personal search all covers messages and notes at once (mail is memo search mail); search messages finds messages by words, people, dates, files and tags; topic search finds discussions by what they were about; the search query language is the full reference.

Message and author rankings: metrics, scores, saved queries and bounded evidence.

Clone this wiki locally