AFK Claude Telegram Bridge

Remote-control Claude Code sessions from your phone via Telegram when AFK (away from keyboard).

When to Use

• “set up telegram bridge” / “configure telegram AFK”
• “enable remote control” / “activate AFK mode”
• “I want to control Claude from my phone”
• Installing this skill on a new machine

What This Skill Does

Installs a complete Telegram ↔ Claude Code bridge that allows you to:

1. Approve/deny tool calls from Telegram inline keyboards
2. Continue tasks by sending new instructions when Claude finishes
3. Auto-approve read-only tools (Read, Glob, Grep, WebSearch, WebFetch)
4. Multi-session support — up to 4 concurrent sessions (S1-S4)
5. Zero dependencies — Python stdlib only

Installation

Run the installer — it copies files, registers hooks, installs /afk and /back commands, and walks you through Telegram bot setup:

bash ~/.claude/skills/afk-claude-telegram-bridge/install.sh

The installer handles everything:

• Copies hook.py, hook.sh, bridge.py to ~/.claude/hooks/telegram-bridge/
• Installs /afk and /back commands to ~/.claude/commands/
• Registers Stop, Notification, and PermissionRequest hooks in ~/.claude/settings.json
• Prompts for your bot token and auto-detects your Telegram group

Restart Claude Code after installation to load the new /afk and /back commands.

Prerequisites

Before running the installer, create a Telegram bot:

1. Open Telegram → search @BotFather → send /newbot
2. Name it “Claude Bridge” (or your preferred name)
3. Copy the bot token
4. Create a Telegram Group with Topics enabled
5. Add the bot to the group as Administrator
6. Send a message in the group (so the bot can detect it)

Usage

Activate AFK Mode

In any Claude Code session:

/afk

You’ll see a confirmation on Telegram: “📡 S1 — AFK Activated”

Deactivate AFK Mode

/back

From Telegram

When Claude needs approval for a tool call, you’ll see:

🔐 S1 — Permission Request
Tool: Bash
`npm install express`
[✅ Approve] [❌ Deny]

When Claude finishes a task:

✅ S1 — Task Complete
I've implemented the login form...
[🛑 Let it stop]

Reply with text to send Claude a new instruction!

Multi-Session

With multiple sessions, prefix instructions:

S1: now add unit tests
S2: push to remote

File Structure

After installation:

~/.claude/hooks/telegram-bridge/
  hook.sh        — Bash entry point
  hook.py        — Hook logic
  bridge.py      — Telegram daemon
  config.json    — Bot token, chat_id, settings
  state.json     — Runtime state
  daemon.log     — Daemon log
  ipc/           — Per-session IPC

~/.claude/commands/
  afk.md         — /afk command
  back.md        — /back command

Commands Reference

Troubleshooting

• Daemon log: cat ~/.claude/hooks/telegram-bridge/daemon.log
• Status: ~/.claude/hooks/telegram-bridge/hook.sh --status
• Manual start: python3 ~/.claude/hooks/telegram-bridge/bridge.py
• Kill daemon: Check PID in state.json, then kill <pid>

Dependencies

• Python 3 (stdlib only — no pip packages needed)
• bash
• Telegram bot token

Credits

Originally built by Greg Motyl (@gmotyl).