cc-afk

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

• Node.js v18+
• Claude Code CLI installed and authenticated
• A Telegram account

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

1. Open Telegram and message @BotFather
2. Send /newbot and follow the prompts to create your bot
3. 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:

1. Entering your bot token (validated against Telegram API)
2. Getting your Chat ID (auto-detected or manual via @userinfobot)
3. 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:

1. Press Escape to interrupt Claude's current turn
2. Type /cc-afk:afk continue what you were doing
3. 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