agent-telegram

Telegram automation CLI for AI agents. It is a fast Go MTProto client with a local IPC daemon, JSON output, schemas, receipts, and an optional HTTP API.

By Aslan Dukaev X · Telegram

Install

bun add -g agent-telegram
npm install -g agent-telegram

From source:

git clone https://github.com/dukaev/agent-telegram
cd agent-telegram
go build -o agent-telegram .

Quick Start

# Show the recommended sign-in options.
agent-telegram

# Login through a local browser using a QR code.
agent-telegram auth

# Start the local IPC server and use Telegram.
agent-telegram server ensure
agent-telegram my-info
agent-telegram chat list
agent-telegram msg list @username --max-items 10
agent-telegram send @username "Hello from agent-telegram"
agent-telegram stop

On an interactive run with no arguments, agent-telegram automatically adds its bundled skill to the nearest existing project .agents/skills. It never creates a project skill directory. If no project skill directory exists, it asks before installing globally to $HOME/.agents/skills.

Manual installation remains available:

agent-telegram skills install agent-telegram

Default Telegram API credentials are built in. To use your own, create an app at my.telegram.org and set TELEGRAM_APP_ID and TELEGRAM_APP_HASH.

QR is the only supported sign-in method. A new login is saved to the selected persistent provider by default; native macOS builds use Keychain.

Command Areas

Run agent-telegram --help, agent-telegram <command> --help, or agent-telegram manifest for the full command catalog.

| Area | Commands | |------|----------| | Server Commands | audit, docs, logs, manifest, run, serve, serve-api, server, session, status, stop, trace | | Authentication Commands | auth, logout, my-info | | Message Commands | bot, msg, send | | Chat Commands | balance, chat, chats, contact, game, gift, open, search, updates, user | | Other Commands | completion, folders, llms-txt, privacy, skills |

Global Options

| Option | Description | |--------|-------------| | --agent | Enable agent-friendly compact JSON, receipts, run IDs, and structured errors | | --confirm | Confirm a destructive or paid operation | | --dry-run | Preview action without executing | | --filter <strings> | Filter results (e.g., 'stars>1000', 'type=channel') | | --include <strings> | Include output fields (comma-separated, supports dot paths) | | --max-items <int> | Maximum array items in JSON output (0 uses verbosity default) | | --max-text-chars <int> | Maximum text field characters in JSON output (0 uses verbosity default) | | --omit <strings> | Omit output fields (comma-separated, supports dot paths) | | --output <string> | Output format: json or ids | | --profile <string> | Session profile (default: default) | | -q, --quiet | Suppress status messages (data still goes to stdout) | | --receipt | Wrap JSON output with trace/action receipt metadata | | --run-id <string> | Agent run ID for correlating multiple commands | | --schema | Output operation schema without executing | | --session-provider <string> | Session provider (default: native platform provider) | | -s, --socket <string> | Path to Unix socket (default: /tmp/agent-telegram.sock) | | --summary | Output a compact result summary | | --verbosity <string> | Output detail: minimal, compact, full, raw (default: full) |

Configuration

agent-telegram auth reads .env automatically.

| Variable | Description | |----------|-------------| | TELEGRAM_APP_ID | Telegram API app ID. Optional because a default is built in. | | TELEGRAM_APP_HASH | Telegram API app hash. Optional because a default is built in. | | TELEGRAM_SESSION | Base64 session for stateless/server deployments. | | AGENT_TELEGRAM_SESSION_PROVIDER | Session provider. Defaults to macOS Keychain on native macOS builds. | | AGENT_TELEGRAM_PROFILE | Named session profile. Defaults to default. | | AGENT_TELEGRAM_API_SECRET | Bearer token for serve-api. | | AGENT_TELEGRAM_RPC_TIMEOUT | RPC timeout, for example 45s or 2m. | | AGENT_TELEGRAM_RUN_ID | Run ID shared across agent commands. |

Agent Usage

Commands write JSON to stdout and logs/status to stderr. Useful automation flags:

agent-telegram server ensure --agent --run-id run_123
agent-telegram msg list @user --verbosity compact --max-items 5 --max-text-chars 120
agent-telegram send @user "hi" --dry-run --agent
agent-telegram <command> --schema
agent-telegram manifest
agent-telegram serve-api --secret "$AGENT_TELEGRAM_API_SECRET" --listen 127.0.0.1:8080

Destructive and paid operations require explicit confirmation with --confirm. The HTTP API is loopback-only by default; use --listen to expose it deliberately. Local file parameters are rejected over HTTP unless their directory is allowed with --file-root. Uploads can instead use multipart/form-data with params and file parts.

For debugging, use audit, logs, trace inspect, and run inspect. Audit/log output is redacted by default.

Policy and bot-flow resilience

The daemon checks policy.json before each protected request. Valid policy changes take effect without restarting the server. If an update is malformed or unreadable, the last valid policy remains active and the server emits a warning without logging peer lists.

Commands whose first positional argument is a peer accept negative group IDs, for example agent-telegram bot step -5424738551 --send /start. --to=-5424738551 remains the universal explicit form. bot step documents --send as canonical and also accepts --text as an alias.

If a reply deadline expires after a write, agent mode reports a retryable partial timeout with the same Run ID and Trace ID. This does not prove that the write failed. Use the returned msg wait and trace inspect commands before deciding whether to act again; do not repeat the write automatically.

Architecture

CLI command -> Unix socket IPC server -> Telegram MTProto

The daemon is explicit: start it with agent-telegram server ensure and stop it with agent-telegram stop. Stopping preserves the Telegram authorization; agent-telegram logout --confirm revokes it. Native macOS builds persist the session in the user's Keychain by default. Other builds use the pluggable provider selected with --session-provider or AGENT_TELEGRAM_SESSION_PROVIDER; TELEGRAM_SESSION remains available for stateless deployments. The default socket is /tmp/agent-telegram.sock; server state and rotating logs live under ~/.agent-telegram/.

Session management commands:

agent-telegram session providers
agent-telegram session status
agent-telegram session use keychain default
agent-telegram session export --confirm
agent-telegram session import --confirm < session.base64
agent-telegram session forget --confirm

agent-telegram get updates --follow advances a cursor using next_offset and epoch. If the daemon restarts or retained updates are evicted, the response sets gap so consumers can resynchronize explicitly.

Development

make build
make test
go run . docs generate
npm run check:web:auth

Landing site

The public landing page is a self-contained application in site/.

npm --prefix site install
npm run site:dev
npm run site:test
npm run site:build

Deploy it from the repository root with npm run site:deploy. For Cloudflare Git integration, set the project root directory to site; the Wrangler configuration in that directory remains the deployment source of truth for agent-telegram.com.

See DEVELOPMENT.md for architecture notes and command patterns.

License

MIT