Skip to main content
plugin CX Codex

agentgram — Claude Code plugin: Telegram messaging

agentgram is a Claude Code and Codex plugin that sends Telegram messages and files through a bot. Agents can also read messages forwarded to that bot.

MIT ★ 1,596 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install agentgram@awesome-codex-plugins
Open on GitHub

What agentgram does

agentgram provides a local CLI for sending Telegram text and files at the user's request. It can also read pending bot updates, including messages manually forwarded into the bot chat. It does not provide full chat history or automatic task-completion alerts.

The setup needs Python 3.12 or newer, a Telegram bot token, and a chat where the bot has been started or added. Set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID in the shell or agent environment. The CLI can be installed from PyPI with pipx install agentgram-tg; Claude Code also supports the marketplace commands below.

Long text can be split into chunks or sent as a document. Bot document uploads have a 50 MB limit, and --split cannot be combined with --parse-mode.

What it helps with

  • send a Telegram message through a bot
  • read messages forwarded to the bot
  • send a local report or other file to Telegram
  • deliver a long message as a document

Example prompts for the agent

  • Send “build finished” to Telegram.
  • Read the messages I forwarded to the bot.
  • Send ./report.md to Telegram with the caption “Report”.

How to install agentgram

Plugin marketplace

/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install agentgram@awesome-codex-plugins

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about agentgram

How do I install agentgram in Claude Code?

Add the marketplace with /plugin marketplace add hashgraph-online/awesome-codex-plugins, then install the plugin with /plugin install agentgram@awesome-codex-plugins.

What does agentgram do?

It gives local agents a CLI for sending Telegram messages and files through a bot. It can also read pending updates, such as messages forwarded to the bot chat.

What does agentgram need to run?

It needs Python 3.12 or newer, a Telegram bot token, and a chat where the bot has been started or added. Set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID in the environment.

Source text

agentgram · MIT
# Agentgram

[![CI](https://github.com/jerryfane/agentgram/actions/workflows/ci.yml/badge.svg)](https://github.com/jerryfane/agentgram/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/jerryfane/agentgram)](https://github.com/jerryfane/agentgram/releases)
[![PyPI](https://img.shields.io/pypi/v/agentgram-tg)](https://pypi.org/project/agentgram-tg/)
[![License](https://img.shields.io/github/license/jerryfane/agentgram)](LICENSE)

Agentgram is a Codex Telegram plugin and agent-neutral messaging helper. It lets
Codex and other local AI agents send explicit, user-requested Telegram messages
through a Telegram bot token and chat id.

Agentgram is intentionally local-first. It does not run a hosted service, and it
does not send automatic completion notifications unless a future task explicitly
adds that behavior.

Use Agentgram when you want a Telegram notification plugin for AI agents, a
simple way to send Telegram messages from Codex, or a reusable local CLI for
agent messaging via a bot token.

## Requirements

- Python 3.12 or newer.
- A Telegram bot token from BotFather.
- A Telegram chat where the bot has been started or added.

## Configuration

Set secrets in your shell or agent runtime environment:

```sh
export TELEGRAM_BOT_TOKEN="123456:bot-token"
export TELEGRAM_CHAT_ID="123456789"
```

Do not put real tokens in tracked files. `.env` and `.env.*` are ignored for
local use, but environment variables are the preferred setup.

For local setup templates, copy [.env.example](.env.example). It contains
variable names only.

## Usage

Install the released CLI from PyPI:

```sh
pipx install agentgram-tg
```

Or install from a git checkout, then put the CLI on your `PATH`:

```sh
git clone https://github.com/jerryfane/agentgram.git ~/.agentgram/agentgram
mkdir -p ~/.local/bin
ln -sf ~/.agentgram/agentgram/bin/agentgram ~/.local/bin/agentgram
```

Run the local CLI:

```sh
agentgram doctor
agentgram send "deploy finished"
agentgram send --silent --no-preview "quiet update"
agentgram send --parse-mode HTML "<b>deploy finished</b>"
```

Send an explicit local file when a user asks for a report, log, diff, archive,
or generated artifact:

```sh
agentgram send-file ./report.md --caption "Report"
agentgram send-file --chat-id 123456789 ./dist/agentgram-plugin.zip
```

Telegram limits bot text messages to 4096 visible characters after entity
parsing. By default, Agentgram rejects over-limit `send` input so agents do not
silently truncate messages. Choose an explicit long-text mode when needed:

```sh
agentgram send --split "long plain text..."
agentgram send --as-file "long plain text..."
agentgram send --as-file --filename report.md "long plain text..."
```

`--split` sends counted plain-text chunks such as `[1/3]` and currently rejects
`--parse-mode`. `--as-file` writes a temporary UTF-8 document and sends it with
Telegram `sendDocument`; no tracked or durable temp file is left behind. Telegram
document uploads through bots are currently limited to 50 MB, and document
captions are limited to 1024 visible characters after entity parsing.

To discover a chat id, first send a message to the bot in Telegram, then run:

```sh
agentgram chat-id
```

For raw Telegram `getUpdates` output:

```sh
agentgram chat-id --raw
```

### Forwarded Inbox

To let an agent read recent context from Telegram without a user-session login,
manually forward the relevant group, channel, or private-chat messages into the
Agentgram bot chat, then ask the agent to read them. The agent can run:

```sh
agentgram inbox
agentgram inbox --limit 100
agentgram inbox --limit 500 --ack
agentgram inbox --since 3h
agentgram inbox --include-plain
agentgram inbox --format compact --output /tmp
agentgram inbox --format jsonl --output /tmp
agentgram inbox --include-plain --download-files --download-dir /tmp --ack
agentgram download-file <file_id> --output /tmp
```

The default inbox mode is equivalent to:

```sh
agentgram inbox --limit 100 --since 24h --forwarded-only --format markdown --peek
```

`--forwarded-only` excludes direct notes sent to the bot. Use
`--include-plain` when the forwarded context is mixed with direct notes to the
agent. `--format markdown` is intended for human-readable transcripts,
`--format compact` is line-oriented context for agents, `--format json` emits a
single stable JSON array, and `--format jsonl` emits one stable JSON record per
line.

Inbox reads pending Telegram Bot API updates only. It is not full Telegram chat
history, does not use MTProto user sessions, and does not run a webhook
receiver. By default, Agentgram does not store message text, captions, sender
names, raw updates, or transcripts in local files. `--output PATH` is the
explicit exception for large imports and writes only to the path requested by
the user or agent. Pending updates can expire, and they can be consumed by
another process using the same bot token.

`agentgram inbox` defaults to `--peek`, so repeated runs do not consume updates.
Peek reads are capped at 100 pending updates, matching Telegram's per-call
`getUpdates` limit. Use `--ack` only after a successful import, or when you
explicitly want to consume the rendered updates:

```sh
agentgram inbox --ack
agentgram inbox --limit 370 --ack
```

With `--ack`, Agentgram can consume up to 500 pending updates by reading
Telegram in batches of 100. Multi-batch reads first write every rendered batch
to a private JSONL staging file and flush it before acknowledging that batch;
the final user-facing output is rendered globally sorted after all batches are
imported. `--format json` is available for single-batch reads up to 100
updates; use `jsonl` for structured multi-batch imports. Telegram acknowledges
updates by offset, which also consumes all lower pending update ids. Agentgram
refuses to ack when doing so would skip fetched updates that were filtered out
and not rendered. Rerun with `--include-plain` or a narrower filter if that
happens.

For large agent imports, prefer a temporary explicit output file so terminal
output truncation does not drop the middle of the forwarded context:

```sh
agentgram inbox --limit 370 --ack --format compact --output /tmp
sed -n '1,120p' /tmp/agentgram-inbox-YYYYMMDDTHHMMSSZ-PID.txt
rm -- /tmp/agentgram-inbox-YYYYMMDDTHHMMSSZ-PID.txt
```

When `--output` points to a directory, Agentgram creates a unique private file
with mode `0600`, prints a receipt with the path, byte count, SHA-256 digest,
and suggested read/delete commands, and keeps message content out of stdout.
It refuses to overwrite existing output files. Use `--output -` to force stdout.

### Telegram File Downloads

To let an agent read a file from Telegram, send or forward the file to the
Agentgram bot chat. Sending a file only to your own saved messages is not
visible to the bot. The agent can then run:

```sh
agentgram inbox --include-plain --download-files --download-dir /tmp --ack
```

`--download-files` downloads file attachments from the rendered inbox records.
Supported attachment types include documents, photos, audio, video, animations,
voice messages, and video notes. `--download-dir` is created if it is missing;
when omitted, Agentgram creates a private temporary directory. Downloaded files
use safe local names, are written with mode `0600`, never overwrite an existing
file, and produce receipts with path, byte count, SHA-256 digest, read hints,
and delete hints. Telegram file URLs are never printed because they contain the
bot token.

With `--ack`, Agentgram acknowledges the fetched Telegram updates only after
the inbox records are rendered and all requested files download successfully.
If a download fails, the fetched updates are left pending so the user can retry
or choose a narrower command.

For advanced workflows where an agent already has a `file_id` from
`--format json` or `--format jsonl`, download that specific file directly:

```sh
agentgram download-file <file_id> --output /tmp
agentgram download-file <file_id> --output /tmp --filename report.pdf
agentgram download-file <file_id> --output ./report.pdf
```

The public Telegram Bot API currently limits bot downloads through `getFile` to
20 MB. Agentgram enforces that limit by default. Telegram's local Bot API server
is the official future path for larger downloads, but Agentgram does not deploy
or configure that server.

Forwarded authorship depends on Telegram's `forward_origin` metadata and the
sender's privacy settings. Agentgram shows the user who forwarded the message to
the bot and, when Telegram provides it, the original user, hidden-user name,
source chat, or source channel. Hidden or uncertain authorship is marked in the
transcript.

Forwarded inbox records are ordered by the original message timestamp from
Telegram's `forward_origin.date` when available, with bot receive order as the
tie-breaker. Human-readable output shows the original group timestamp first.
Structured JSON/JSONL output also includes the forwarded-copy bot timestamp as
`date_iso` and the original timestamp as `original_date_iso`.

`getUpdates` cannot be used while the same bot has an outgoing webhook set.
Remove the webhook or use a bot token dedicated to Agentgram inbox reads.

To check whether the local git checkout is current using existing local refs, or
to update with a fast-forward-only pull:

```sh
agentgram update --check
agentgram update
```

`agentgram update` refuses dirty worktrees, validates the checkout after pulling,
and prints runtime-specific next steps when it can detect them. Codex plugin
users should reinstall or refresh the plugin and start a new thread so updated
skills are loaded.

## Codex Plugin

The Codex plugin skill lives in `skills/agentgram/SKILL.md`, with the plugin
manifest at `.codex-plugin/plugin.json`. The skill tells Codex to use the local
`agentgram` CLI as the execution path. This repository also contains a public
Codex marketplace file so Agentgram can be installed as a Codex Telegram plugin.

To install Agentgram from the public Codex marketplace file in this repository:

```sh
codex plugin marketplace add jerryfane/agentgram --ref main
codex plugin add agentgram@agentgram
```

Start a new Codex thread after installing so the Agentgram skill is loaded.
Use `codex plugin marketplace upgrade agentgram` before reinstalling when you
want newer Agentgram releases.

When a user asks an agent to send a Telegram message, the agent should:

1. Run `agentgram doctor`, or `bin/agentgram doctor` only from this repository
   checkout.
2. Run `agentgram send "message"` for short text, `agentgram send-file <path>`
   for an explicit local file, or `agentgram send --split/--as-file` for long
   text, if setup is valid.
3. Run `agentgram inbox` when the user asks to read recently forwarded Telegram
   messages.
4. Run `agentgram inbox --include-plain --download-files --download-dir /tmp
   --ack` when the user asks to download and inspect a file they sent or
   forwarded to the Agentgram bot. If multiple files are present, list them and
   ask which one to inspect.
5. Confirm ambiguous file paths before sending and never send generated files
   automatically just because a task completed.
6. Avoid direct Telegram API calls unless the user explicitly asks to bypass the
   Agentgram CLI.

## Troubleshooting

- Bot was not started: open Telegram, send any message to the bot, then run
  `agentgram chat-id` again.
- Bad token: run `agentgram doctor`; malformed tokens fail locally, and revoked
  or wrong tokens fail the Telegram `getMe` check.
- Missing chat id: set `TELEGRAM_CHAT_ID`, or pass `--chat-id <id>` for a
  one-off send after the user provides the target chat.
- Message too long: use `agentgram send --split` for plain text chunks or
  `agentgram send --as-file --filename <name>` to deliver it as a document.
- File rejected: verify the path is a readable, non-empty regular file at or
  below Telegram's bot upload limit.
- Download rejected: verify the file was sent or forwarded to the Agentgram bot
  chat and is within the public Bot API download limit of 20 MB.
- Forbidden chat: add the bot to the target chat or start a private chat with
  it, then retry after confirming the chat id.
- Inbox is empty: forward messages to the bot chat and rerun before Telegram's
  pending updates expire. Check that another process has not consumed updates
  from the same bot token.
- Inbox ack is refused: rerun with `--include-plain` or narrower filters so
  Agentgram does not skip unrendered pending updates.
- Webhook conflict: remove the outgoing webhook or use a separate bot token for
  Agentgram inbox reads.
- Telegram API errors: Agentgram prints Telegram's error description without the
  bot token. Re-run `agentgram doctor` before retrying.

## Release Checks

Before release, run:

```sh
python3 -m unittest discover -s tests -v
python3 scripts/validate_manifest.py
git diff --check
```

See [docs/release-checklist.md](docs/release-checklist.md) for the full
checklist and fresh-clone smoke.

## Status

Released. Agentgram `v0.2.x` includes the Telegram CLI, file sending, long-text
delivery modes, Codex skill packaging, public Codex marketplace metadata, update
ergonomics, release docs, and CI checks.

© Jerry Fane · MIT · hashgraph-online/awesome-codex-plugins

Similar plugins

Everything for Telegram bots →

From the same set391

The whole set →
anime-reaction-gif anime-reaction-gif — a plugin for Claude Code and Codex that builds looping reaction GIFs and MP4s from generated pose sheets. It drives image_gen for key poses, then hands the frames to FFmpeg for timing and export. CX Codex ★ 1,596repo stars aient Connect Claude Code to Aient’s MCP server to inspect production telemetry, investigate problems, and work through remediation. Useful when an agent needs operational context. CX Codex ★ 1,596repo stars aident-loadout aident-loadout — a remote MCP server that gives your agent access to the apps you authorise and 400+ skills, with a single setup shared across Claude, Claude and other clients. CX Codex ★ 1,596repo stars agentmart agentmart connects a remote MCP server offering persistent agent utilities like webhook inboxes, memory lockers, and queues. Helps when an agent needs infrastructure that stays online. CX Codex ★ 1,596repo stars agentdomains agentdomains lets the agent claim a public name like yourname.makes.fyi and edit its DNS records from the CLI — for a site, a webhook, or a server it just started. CX Codex ★ 1,596repo stars agent-vision agent-vision is a macOS plugin that connects a Mac’s built-in camera to a coding assistant conversation through one-shot JPEG captures. CX Codex ★ 1,596repo stars amq-cli amq-cli is a Claude Code plugin that lets coding agents exchange requests and replies through a local file queue, continuing conversations in threads. CX Codex ★ 1,596repo stars abuzzhive Connects an agent to AbuzzHive public Q&A boards, where agents post errors and propose fixes to each other. A hook triggers find_by_error automatically after every failed shell command. CX Codex ★ 1,596repo stars

More in the catalog

Project sponsors

Companies that keep this analytics open