afk

/cc-afk:afk — Remote AFK Mode via Telegram

You are helping the user manage AFK mode, which bridges Claude Code with Telegram for remote interaction.

Arguments

The user may pass arguments after /cc-afk:afk:

• Any task description → Start AFK mode, then process the task (e.g. /cc-afk:afk refactor the auth module)
• No args or start → Start AFK mode (wait for Telegram messages)
• off or stop → Stop AFK mode
• setup → Configure Telegram bot token and chat ID
• status → Check if bridge is running

If the argument is not a known command (start, off, stop, setup, status), treat it as a task to execute after entering AFK mode.

Setup Flow

If config doesn't exist yet, check BOTH locations:

• $CLAUDE_PLUGIN_DATA/config.json (plugin data dir)
• ~/.cc-afk/config.json (fallback)

If neither exists, guide the user through setup:

Step 1: Get bot token

Ask the user for their Telegram Bot Token. Tell them to:

1. Open Telegram and message @BotFather
2. Send /newbot and follow the prompts
3. Copy the bot token

Step 2: Validate token

node "${CLAUDE_PLUGIN_ROOT}/dist/setup-validate.js" validate-token "<TOKEN>"

Output: {"ok":true,"botName":"@name"} or {"ok":false,"error":"..."}

If invalid, ask for the token again.

Step 3: Get chat ID

Ask the user for their Chat ID (they can get it from @userinfobot on Telegram), OR offer to auto-detect:

Tell the user to send any message to their bot on Telegram, then run:

node "${CLAUDE_PLUGIN_ROOT}/dist/setup-validate.js" detect-chat "<TOKEN>"

Output: {"ok":true,"chatId":123,"name":"..."} or {"ok":false,"error":"..."}

If auto-detect fails, ask for manual input.

Step 4: Save config

CLAUDE_PLUGIN_DATA="${CLAUDE_PLUGIN_DATA}" node "${CLAUDE_PLUGIN_ROOT}/dist/setup-validate.js" save-config "<TOKEN>" <CHAT_ID> [PORT]

Output: {"ok":true,"path":"..."} or {"ok":false,"error":"..."}

Step 5: Test message

node "${CLAUDE_PLUGIN_ROOT}/dist/setup-validate.js" test-message "<TOKEN>" <CHAT_ID>

Output: {"ok":true} or {"ok":false,"error":"..."}

Tell the user to check Telegram for the test message.

Start Flow

1. Check if config exists at $CLAUDE_PLUGIN_DATA/config.json or ~/.cc-afk/config.json. If not, prompt setup first.
2. Check if bridge is already running by reading $CLAUDE_PLUGIN_DATA/bridge.port (or ~/.cc-afk/bridge.port) and hitting http://127.0.0.1:<port>/api/health.
3. If already running, inform the user "AFK mode is already active."
4. If not running, start the bridge:

CLAUDE_PLUGIN_DATA="${CLAUDE_PLUGIN_DATA}" nohup node "${CLAUDE_PLUGIN_ROOT}/dist/bridge.js" > /dev/null 2>&1 &

5. Wait 3 seconds, then verify with a health check:

curl -s http://127.0.0.1:19211/api/health

6. If health check passes, tell the user: "AFK mode is active! You'll receive updates in Telegram. Use /cc-afk:afk off to deactivate."
7. If health check fails, suggest checking if the config is correct and the bot token is valid.
8. If a task was provided as an argument, process it now — do the work (read files, edit code, run commands, etc.) as you normally would. Permission requests and tool results will be forwarded to Telegram via hooks while you work. When done, send a summary to Telegram via the notification endpoint.
9. After the task is complete (or if no task was given), enter the remote prompt loop (see below) to wait for follow-up messages from Telegram.

Remote Prompt Loop

After starting AFK mode, enter this loop to process messages from Telegram within the current session. This gives full context and normal permission handling.

Read the port from $CLAUDE_PLUGIN_DATA/bridge.port or ~/.cc-afk/bridge.port (default: 19211).

Loop:

1. Wait for a message from Telegram (blocks up to 55 seconds):

curl -s --max-time 60 http://127.0.0.1:<port>/api/wait-for-message

Response: {"status":"message","text":"user's message"} or {"status":"timeout"}

2. If curl fails (non-zero exit code) — the bridge was shut down (e.g. user sent /stop in Telegram). Immediately exit the loop. Tell the user "AFK mode ended." and stop. Do NOT attempt to restart the bridge or reconnect.

3. If status is "timeout", go back to step 1 (keep waiting).

4. If status is "message", process text as if the user typed it here — read files, edit code, run commands, etc. Do whatever the message asks.

5. After processing, send your response summary to Telegram:

curl -s -X POST http://127.0.0.1:<port>/api/notification -H "Content-Type: application/json" -d '{"title":"Done","message":"<summary of what you did>"}'

6. Go back to step 1.

Exit conditions — stop the loop immediately and do NOT reconnect:

• If curl to /api/wait-for-message fails (connection refused, reset, or any non-zero exit code) — bridge was shut down
• If the user sends "exit" or "quit" via Telegram

Stop Flow

1. Check for port file at $CLAUDE_PLUGIN_DATA/bridge.port or ~/.cc-afk/bridge.port
2. If found, read the port and send:

curl -s -X POST http://127.0.0.1:<port>/api/shutdown

3. Confirm bridge has stopped.
4. If no port file, tell the user bridge is not running.

Status Flow

1. Check for port file
2. If exists, hit health endpoint and report status (include pending permissions count)
3. If not, report "Bridge is not running."

Important Notes

• The bridge runs as a background process, separate from this Claude Code session
• Hooks are always registered but become no-ops when the bridge isn't running (zero overhead)
• Environment variables TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID can be used instead of config file
• Config is stored at $CLAUDE_PLUGIN_DATA/config.json when installed as a plugin
• Remote prompts work in two modes:
  1. Same-session loop (primary): Claude polls /api/wait-for-message and processes messages within the current session, with full context and normal permissions
  2. Separate claude -p (fallback): If the loop isn't active, messages spawn independent Claude sessions
• Use /cancel in Telegram to cancel a running remote prompt (fallback mode only)
• If Claude is busy, additional messages are queued and processed in order