cc-afk
Control Claude Code remotely via Telegram while you're away from your desk.
cc-afk is a Claude Code plugin that bridges your CLI session with a Telegram bot. Activate it with /cc-afk:afk, walk away, and manage everything — permissions, tool results, notifications — from your phone.
How It Works
┌──────────────────┐ hooks (stdin JSON) ┌──────────────────┐
│ Claude Code │ ──────────────────────────► │ Hook Handler │
│ (CLI session) │ │ (short-lived) │
└──────────────────┘ └────────┬─────────┘
│ HTTP localhost
▼
┌──────────────────┐ Telegram Bot API
│ Bridge Service │ ◄──────────────────► 📱 You
│ (persistent) │ (long-polling)
└──────────────────┘
- Hook handler — short-lived process triggered by Claude Code events, forwards them to the bridge via HTTP
- Bridge service — persistent Express server + Telegraf bot that relays messages between Claude Code and Telegram
- Skill (
/cc-afk:afk) — starts/stops the bridge and runs setup from inside a Claude Code session
What you get in Telegram
- Remote prompts — send messages to Claude and get responses, just like being at your desk
- Permission requests with inline Allow / Deny / Allow Always buttons (5-min timeout, defaults to deny)
- Tool results batched in 2-second windows to avoid spam
- Session notifications when Claude finishes or needs attention
Prerequisites
Installation
Option A: Marketplace (recommended)
Inside a Claude Code session:
/plugin marketplace add imskinner/cc-afk
/plugin install cc-afk@cc-afk
Option B: Local development
git clone https://github.com/imskinner/cc-afk.git
cd cc-afk
npm install
Then launch Claude Code with the plugin loaded:
claude --plugin-dir /path/to/cc-afk
No build step needed — bundled dist/ files are committed to the repo.
Setup
1. Create a Telegram bot
- Open Telegram and message @BotFather
- Send
/newbot and follow the prompts to create your bot
- Copy the bot token it gives you (looks like
123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)
2. Run setup
Inside a Claude Code session with the plugin installed:
/cc-afk:afk setup
Claude will walk you through:
- Entering your bot token (validated against Telegram API)
- Getting your Chat ID (auto-detected or manual via @userinfobot)
- Saving config and sending a test message
Usage
Start AFK mode
/cc-afk:afk
The bridge starts, the Telegram bot connects, and you'll see "AFK mode activated" in your chat. Walk away.
Start AFK mode with a task
/cc-afk:afk refactor the auth module
Starts the bridge and begins working on the task immediately. Permission requests and tool results are forwarded to Telegram while Claude works. When the task is done, Claude waits for follow-up messages from Telegram.
Go AFK mid-task
If Claude is already working on something and you need to leave:
- Press Escape to interrupt Claude's current turn
- Type
/cc-afk:afk continue what you were doing
- Walk away — Claude picks up where it left off, now with Telegram forwarding active
Since it's the same session, Claude has full context of everything before the interrupt.
Interact from Telegram
- Send any text message — Claude processes it in your current session with full context
- Permission requests appear as messages with Allow/Deny/Allow Always buttons — tap to respond
/status — check bridge status and pending permissions/cancel — cancel a running remote prompt/stop — deactivate AFK mode and shut down the bridge
Stop AFK mode
From inside Claude Code:
/cc-afk:afk off
From Telegram:
/stop
Configuration
Config is stored at $CLAUDE_PLUGIN_DATA/config.json (or ~/.cc-afk/config.json as fallback):
{
"telegram": {
"botToken": "your-bot-token",
"chatId": 123456789
},
"bridge": {
"port": 19211,
"permissionTimeoutSeconds": 300
}
}
Environment variables also work:
| Variable | Purpose |
|---|
TELEGRAM_BOT_TOKEN | Bot token (overrides config file) |
TELEGRAM_CHAT_ID | Chat ID (overrides config file) |
Development