telegram-to-agent-skill-cli 0.7.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, which collects API credentials, signs you in, installs the agent skill and offers the initial sync.

# 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.

Why skill + CLI, not an MCP server

• Zero context tax. MCP tool schemas eat thousands of tokens in every session. A skill loads on demand; the CLI costs nothing until used.
• One integration, every agent. The same tg commands work in Claude Code, Codex, and anything else with a shell.
• No session juggling. MCP servers spawn per agent session and fight over the Telethon session file. Here one sync process writes and any number of agent sessions read.

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.

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.