BuddyTG

Use your own Telegram account from the terminal. Send messages and files, export Saved Messages, and answer Codex and Claude Code approval prompts from your phone.

Install Source on GitHub

$ buddytg send me "Deploy finished"
Sent (message id 4821).

Saved Messages

Deploy finished

18:42

$ buddytg ask --option "main=Use main" \
    --option "feature=Use feature branch" \
    "Which branch should I use?"
Waiting for a Telegram response…
main

Your BuddyTG bot

Which branch should I use?

18:43

Use main Use feature branch

# Claude Code runs this for each permission request
$ buddytg hook permission < request.json
Waiting for a Telegram response…
{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow"}}}

Your BuddyTG bot

🔐 Claude Code approval request

Project: BuddyTG
Tool: Bash

bun run build

Allow this action?

18:44

Allow once Deny

Commands

Send a message

To Saved Messages, a username, a phone number, a group ID from chats, or a t.me link.

buddytg send @username "Hello"

Send a file

Shows the resolved recipient and the file manifest, then waits for you to type the recipient's ID.

buddytg file send @username archive.zip

Download a file

From a copied message link or a peer and message ID. An existing file is never replaced.

buddytg file download https://t.me/group/456 --to ~/Downloads

List chats

Names and the numeric IDs you pass to send. Negative IDs are groups and channels.

buddytg chats --limit 200 --archived

Export Saved Messages

Markdown, oldest first, with timestamps, message IDs, tags, forwards and reply links.

buddytg bookmarks notes/telegram.md --download-media

Notify yourself

A normal push notification from your own bot. HTML and MarkdownV2 formatting work.

buddytg notify --silent "Build finished"

Ask and wait

Sends a question with optional buttons and prints the answer to stdout for a script to read.

buddytg ask --option "yes=Ship it" "Deploy now?"

Log in

Scan a QR code from Settings, Devices, Link Desktop Device. Use --phone for a code instead.

buddytg login

Agents

Approval prompts on your phone

Add one PermissionRequest hook to Codex or Claude Code. Each request arrives in Telegram with Allow once and Deny buttons. A tap allows one action and never creates a standing rule.

If Telegram is not set up, unreachable, or the request times out, the hook returns no decision and the agent shows its own local dialog.

{
  "hooks": {
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "buddytg hook permission",
            "timeout": 600
          }
        ]
      }
    ]
  }
}

pi extension

Typed tools for pi: whoami, chats, send and send file. /buddytg login runs the QR login inside the pi terminal. Recipients must be numeric chat IDs.

Sends run without a confirmation dialog by default. Start pi with BUDDYTG_CONFIRM_SENDS=1 to approve each one.

# one session
pi -e ./pi/index.ts

# every project
pi install .

# confirm every send
BUDDYTG_CONFIRM_SENDS=1 pi

Safety

Secrets: API credentials, the Telegram session and the bot token go in the macOS Keychain. On Linux they are files in ~/.config/buddytg/secrets, a 0700 directory with 0600 files. Nothing is written to the repository.
File sends: You type the recipient's numeric ID before an upload starts. There is no --yes flag. Directories, empty files, URLs and symlinks are refused, and a file that changes after the manifest is not sent.
Downloads: Remote names are sanitized and an existing file is never replaced. Data streams into a hidden 0600 temporary file and is published only when complete.
Approvals: Only a reply to that exact prompt, from your own private chat, counts. Buttons carry a random nonce, so an old tap cannot answer a new request.
Logout: buddytg logout revokes the Telegram session and deletes every stored secret.

Install

You need macOS or Linux, Bun, a Telegram account, and an api_id and api_hash from my.telegram.org/apps.

The first login asks for those two values and stores them. Notifications, questions and approvals also need your own bot. Create one with @BotFather, send it /start, then run bun run buddytg bot login.

git clone https://github.com/OxFrancesco/BuddyTG.git
cd BuddyTG && bun install

bun run buddytg login
bun run buddytg send me "Hello from BuddyTG"

bun run build
# then put dist/buddytg on your PATH