telegram-to-agent-skill-cli 0.8.0

English · Русский

Ask your coding agent "what did the team discuss this week?" and it actually knows.

Half of every project's real context lives in Telegram: decisions made in group chats, specs shared as files, links that never made it to the wiki. This tool gives that context to Claude Code, Codex, or any agent that can run a CLI.

The tg CLI signs in as you (MTProto via Telethon), syncs your chats into a local SQLite index with full-text search, and installs an agent skill that activates itself whenever you mention your chats. Agents read locally: instant, offline, no rate limits. The CLI touches Telegram only to sync, download files, or (after your explicit "yes") send a reply.

Install

Pick any of the three. Each one ends in the interactive setup wizard: sign-in, agent skill, desktop apps, initial sync. No API keys needed: press Enter and the built-in Telegram Desktop keys are used (your own from my.telegram.org stay recommended for heavy syncing).

# with uv (recommended)
uv tool install telegram-to-agent-skill-cli && tg setup

# one-shot, no prior install
uvx --from telegram-to-agent-skill-cli tg setup

# via npm, if Node is your home turf
npx telegram-to-agent-skill-cli

Developers clone the repo and run ./install.sh (editable install, same wizard). Details: docs/INSTALL.md.

Claude Code users can also add the repo as a plugin marketplace, which installs the skill without touching the shell:

/plugin marketplace add voftik/telegram-to-agent-skill-cli
/plugin install telegram-context@telegram-to-agent-skill-cli

The CLI itself still comes from PyPI (the skill will tell you the install command if tg is missing).

Update

tg update          # checks PyPI, upgrades, refreshes the agent skill
tg update --check  # just report; agents read update.update_available from `tg status --yaml`

The CLI never phones home on its own in data commands: the passive version hint reads a local cache and prints to stderr only in interactive sessions. Set TG_UPDATE_CHECK=0 to silence it.

Desktop chat apps

Claude Desktop, Perplexity and ChatGPT (chat mode) cannot run a CLI, but they can run local MCP servers. One command wires them to the same local index through tg mcp, a read-only bridge that never touches the Telegram session:

tg connect

It detects the apps, writes their configs, self-tests the bridge and offers tg autosync (a scheduled refresh that keeps the index fresh). Details per app: docs/DESKTOP-APPS.md (in Russian).

Why skill-first (and where the MCP bridge fits)

• Zero context tax. MCP tool schemas eat tokens in every session. A skill loads on demand; the CLI costs nothing until used. Coding agents (Claude Code, Codex) get the full skill + CLI.
• One integration, every agent. The same tg commands work in Claude Code, Codex, and anything else with a shell.
• No session juggling. Sync is owned by one CLI process on the host; any number of agent sessions read the SQLite index. The bundled tg mcp bridge follows the same rule: it is a read-only adapter for hosts without a shell, six small tools, no Telegram session, no sends.

How it works

flowchart LR
    TG[("Telegram<br/>(your account, MTProto)")]
    subgraph LOCAL["Your machine"]
        SYNC["tg sync / refresh<br/><i>on demand</i>"]
        DB[("SQLite + FTS5<br/>messages · attachments · links · threads")]
        FILES["files/ + extracted text<br/>pdf · docx · xlsx · pptx"]
        QUERY["tg brief · search · thread<br/>links · files · style"]
    end
    subgraph AGENTS["Agents"]
        CC["Claude Code<br/><i>skill auto-activates</i>"]
        CX["Codex<br/><i>via AGENTS.md</i>"]
    end
    TG -->|history| SYNC --> DB
    TG -->|lazy download| FILES
    DB --> QUERY
    QUERY --> CC & CX
    FILES --> CC & CX
    CC & CX -.->|"send only with --confirm<br/>after explicit user yes"| TG

What agents can do with it

Safety model

• The Telethon session file equals full account access. It lives in a private data dir (0700/0600), never in git, never in cloud-synced folders; every machine signs in separately.
• Every write to Telegram (send, edit, delete) is a dry-run without --confirm. Confirmed mutations land in a durable journal before the network call.
• Untrusted attachments face budgets: size checks before download, zip-bomb guards, streaming hashes, private file modes.
• Use your own api_id and api_hash. The tool syncs politely (delays, jitter, FloodWait handling) and reads locally.

How it compares

Honest comparison with the other ways to give an agent your Telegram (state of the ecosystem, August 2026):

¹ chigwell/telegram-mcp, chaindead/telegram-mcp, overpod/mcp-telegram and similar. They still fit when your agent lives in claude.ai web, which cannot spawn local processes at all; chaindead's drafts-only design is a genuinely safe touch. Desktop hosts (Claude Desktop, Perplexity, ChatGPT desktop) are covered by the bundled read-only tg mcp bridge instead. ² Telethon/GramJS allow one process per session file; MCP servers spawn per agent session and collide (the shared-daemon setups that avoid this need extra configuration).

What the fork adds over upstream tg-cli

Credits

A fork of jackwener/tg-cli (Apache-2.0): the clean local-first core is theirs. Built on Telethon. License: Apache-2.0.