Agent2Telegram AGENTS.md

AGENTS.md — install playbook for an AI agent

This file is written for an AI coding agent (Codex, Claude Code…) tasked with installing Agent2Telegram on a fresh machine for a non‑technical user. Follow it as a recipe. Do not improvise around the security rules.

Your goal

Get the Agent2Telegram bridge running so the user can talk to their agent from Telegram, then verify it actually works and hand the user a short summary.

Hard rules (do not break)

1. Never weaken security. The bridge lets a Telegram user run commands on this machine. The allowed_user_ids list must contain only the owner's real Telegram user id. Never set it to empty "to make it work", never add unknown ids, never disable the check.
2. Never print, paste, or commit the bot token. It is a secret. It lives only in ~/.config/agent2telegram/config.json (mode 0600) or the TELEGRAM_BOT_TOKEN env var.
3. Do not use shell=True or interpolate user input into shell strings anywhere.
4. If a step needs a secret or a decision only the user can make (token, which agent, their Telegram id), ask the user — don't guess.

Prerequisites to check first

Run these and fix what's missing before installing:

• python3 --version → must be 3.10+. If missing, install Python 3.
• git --version → needed to fetch the repo. Install if missing.
• The agent CLI to bridge must be installed and logged in:
  • Claude Code: claude --version and a prior claude login.
  • Codex: codex --version and a prior codex login.
  • Test it works headlessly, e.g. claude -p "say hi" or codex exec "say hi". If the agent CLI isn't installed/authenticated, stop and ask the user to do that (it requires an interactive login you can't complete for them).

Install steps

git clone https://github.com/petrludwig-collab/Agent2Telegram.git
cd Agent2Telegram
python3 -m pip install --user .          # or: --user --break-system-packages

Configure

Prefer the interactive wizard if the user is present:

python3 -m agent2telegram setup

If you must configure non‑interactively, ask the user for (a) which agent and (b) the bot token and their Telegram user id, then write ~/.config/agent2telegram/config.json:

{ "agent": "codex", "token": "<ASK THE USER>", "allowed_user_ids": [<ASK THE USER>] }

…and chmod 600 it. To get the user's id: have them message the bot, then read it from getUpdates, or ask them to send /id to the bot once it's running.