teleloom

Teleloom connects your Telegram accounts and bots to the agent you already use. Find messages across chats, catch up on discussions, build summaries with source links, inspect documents, and prepare actions you can review before they run.

One local owner manages connections and state. Multiple agent clients share it; you choose the accessible chats and the permissions for each account.

What you can do

67 MCP tools and six portable skills: connect, read, inbox, digest, send and broadcast. See the tool reference for exact contracts and limits.

Related MCP server: telegram-mcp

Quick start

Requires Git, uv and Python 3.12–3.14. User accounts need your own Telegram API ID/hash from my.telegram.org. Bots use a bot token. Credentials are entered locally, outside an agent conversation.

git clone --single-branch https://github.com/starsinc1708/teleloom.git
cd teleloom
uv sync --frozen
uv run teleloom init
uv run teleloom auth user --profile personal --ui browser
uv run teleloom profile list

On your phone, open Telegram → Settings → Devices → Link Desktop Device and scan the QR. A working OS credential store is required to save the session. For headless hosts, bots, read restrictions and first-use troubleshooting, follow the English guide or Russian guide.

Connect a client and install its skills:

uv run teleloom config client --client codex
uv run teleloom skills install --client codex

Merge the printed fragment into the existing client configuration, then reconnect MCP. Use claude, opencode (v2), opencode-v1, hermes or pi for other clients. Existing skills are preserved unless you explicitly request replacement. Client paths and discovery checks.

For OpenCode 2 or Hermes, register MCP through the installed client's CLI:

uv run teleloom config client --client opencode --install
uv run teleloom skills install --client opencode
uv run teleloom config client --client hermes --install
uv run teleloom skills install --client hermes

Choose the pair for your client, then reconnect MCP (opencode reload for a running OpenCode service). --install is available in the current source checkout; v0.5.0 only prints fragments. An identical connection is preserved; a conflicting teleloom entry requires manual review. Hermes skills follow hermes config path, including its active profile and HERMES_HOME.

Try this first:

Check server status and list profiles. Ask me to select a profile and one chat. Read its latest 20 messages without marking them as read. Summarize the main topics with message links and state any missing context. Do not send messages or change settings or permissions.

Control and privacy

• New profiles can read all chats accessible to the account. Use selected read policy to restrict access; the setup guide explains the independent tool and chat gates.

• Sending and other external changes require their own permissions and an immutable preview plus confirmation. An uncertain delivery is recorded as unknown and is never automatically resent.

• An explicit human instruction to send to exact recipients can authorize that previewed send and selected local files through owner_authorized=true. Permanent allowlists and file roots stay unchanged. Plan authorization.

• Telegram credentials stay in the OS keyring or supplied environment. State and exports stay in your local data directory. Your chosen agent/model provider receives the evidence you request; optional external analysis is explicit.

• Reading does not acknowledge messages. Bot history covers collected observations, and search/digest results disclose their scope and gaps.

The confirmation flag is trusted input from your agent client; it is not independent proof of a human approval. All local clients share one trusted OS owner. Security model and vulnerability reporting.

Clients and optional features

Optional extras: pdf, ocr, transcription and jev. Start with the base installation; enable only the engines you need. Media, attachments, deployment. Native connection observations and testing limits are recorded in acceptance; discovery does not establish model workflow quality.

Develop and contribute

Report reproducible bugs and propose workflows in Issues. Read CONTRIBUTING; coding agents start with AGENTS.md. Run checks for the behavior you change. A substantial release gets one full run, one canonical build and artifact identity verification.

Teleloom v0.5.0 is the first public release, published with a fresh Git history. The Python package, module, CLI and MCP server are named teleloom; runtime skills use the teleloom- prefix. Install from this repository or its release artifacts; no PyPI distribution is claimed. Changelog · Documentation.

MIT licensed. Inspired by chigwell/telegram-mcp, implemented independently. Teleloom is an independent project, unaffiliated with Telegram.