@probelabs/afk

AFK - Control Claude Code from Anywhere

Your code doesn't stop when you leave your desk. Get Telegram notifications for Claude Code actions and approve them from anywhere. No cloud dependencies, no third-party servers.

⚡ Quick Start

3 commands, 2 minutes, full mobile control:

# 1. Install and setup
npm install -g @probelabs/afk
afk setup  # Creates your Telegram bot

# 2. Go remote
afk        # Smart toggle: installs hooks and enables remote mode

That's it! Claude Code now sends approval requests to your phone. 📱

What happens next?

• Claude starts a task → You get a Telegram notification
• Tap Approve → Claude continues
• Tap Deny → Claude stops and asks for guidance
• Step away confident your code is safe

🎯 Why AFK?

📱 Mobile Development Freedom

• ☕ Step away during long refactors
• 🚇 Approve changes from your commute
• 🏖️ Monitor critical tasks remotely
• 🔒 Add approval gates for sensitive operations

🔐 Privacy First

• Zero cloud dependencies
• Direct Telegram connection
• Your bot, your control
• Local state only

🚀 Smart Integration

• Works with Claude Code's permission system
• Multi-project session management
• Auto-approve safe operations
• Timeout protection

🛠️ Commands

Basic Usage

afk              # Smart toggle: install if needed, then toggle mode
afk on           # Enable remote approvals  
afk off          # Disable remote approvals
afk status       # Check current mode

Setup & Installation

afk setup        # Interactive Telegram bot setup
afk install      # Install Claude Code hooks
afk uninstall    # Remove hooks

Testing & Debug

afk telegram test    # Test Telegram connection
afk debug on         # Enable debug logging

🔧 How it Works

1. Hook Integration AFK hooks into Claude Code at key decision points:

• PreToolUse: Intercepts risky operations (file edits, bash commands, web requests)
• SessionStart: Notifies when new coding sessions begin
• Stop: Enables follow-up conversations when tasks complete

2. Smart Permissions

• Respects Claude's existing allow/deny lists
• Auto-approves safe tools like Read and Grep
• Creates permanent patterns from one-time approvals

3. Mobile Approval Flow

Claude wants to edit file.js
        ↓
AFK checks: Local or Remote mode?
        ↓
Sends Telegram notification with context
        ↓
You tap: [Approve] [Deny] [Allow All] [Ask Claude UI]
        ↓
Claude proceeds or stops based on your choice

4. Session Management

• Each Claude session gets unique ID
• Messages tagged with project and session
• Reply threading maintains conversation context

🏗️ Architecture

System Overview

┌──────────────────┐         ┌──────────────────┐         ┌──────────────────┐
│                  │         │                  │         │                  │
│   Claude Code    │────────▶│   AFK Hooks      │────────▶│   Telegram API   │
│                  │         │                  │         │                  │
│  • PreToolUse    │         │ • Intercepts     │         │ • Distributed    │
│  • SessionStart  │         │ • Routes msgs    │         │   polling        │
│  • Stop events   │◀────────│ • Manages state  │◀────────│ • Button handling│
│  • Notifications │         │                  │         │                  │
└──────────────────┘         └──────────────────┘         └──────────────────┘
        ▲                            │                            
        │                            │                            
        │                            ▼                            
        │                    ┌──────────────────┐                
        │                    │                  │                
        └────────────────────│   Local State    │                
                             │                  │                
                             │ • ~/.afk         │               
                             │ • Mode (on/off)  │               
                             │ • Session map    │               
                             │ • Approvals      │               
                             └──────────────────┘               

Hook Integration Points

PreToolUse Hook - Gates tool execution:

• Checks current mode (local/remote)
• Validates against Claude's existing permissions
• Sends approval requests to Telegram in remote mode
• Waits for user response with timeout

SessionStart Hook - New session notifications:

• Notifies when Claude begins new coding sessions
• Waits for initial instructions or "Continue"
• Can inject follow-up tasks via process exit code 2

Stop Hook - Task completion handling:

• Sends completion notifications to Telegram
• Enables follow-up conversations and instructions
• Supports session continuation or closure

⚙️ Configuration

Run afk setup for interactive configuration. The wizard:

• 🤖 Creates your Telegram bot via @BotFather
• 🔑 Securely stores bot token (masked input)
• 💬 Auto-detects your chat ID
• ✅ Tests the connection
• 💾 Saves to ~/.afk/config.json

Config file:

{
  "telegram_bot_token": "YOUR_BOT_TOKEN",
  "telegram_chat_id": "YOUR_CHAT_ID",
  "timeout_seconds": 3600,
  "intercept_matcher": "Bash|Edit|Write|MultiEdit|WebFetch|mcp__.*",
  "auto_approve_tools": ["Read"]
}

Configuration Options

Option	Description	Default	Options
timeout_seconds	Approval timeout	3600 (1 hour)	Any positive number, 0 for infinite
intercept_matcher	Tools to intercept	"Bash|Edit|Write|MultiEdit|WebFetch|mcp__.*"	Regex pattern
auto_approve_tools	Always allow these	["Read"]	Array of tool names

Note: Additional options like timeout_action and respect_claude_permissions can be added manually to the config file if needed.

Environment Variables

export TELEGRAM_BOT_TOKEN="your_token"    # Alternative to config file
export TELEGRAM_CHAT_ID="your_chat_id"    # Alternative to config file
export CC_REMOTE_STOP_TIMEOUT=21600       # Stop event timeout (6 hours)

🔐 Smart Approval System

Permission Flow:

• Check Claude's existing permissions → Use those if set
• Check auto-approve list → Safe tools go through automatically
• Check mode → Local uses Claude UI, Remote sends to Telegram
• Telegram approval → Tap [Approve], [Deny], [Allow All], or [Ask Claude UI]

Smart Patterns: When you tap [Allow All], AFK creates permanent rules like:

• Bash(npm test:*) - Allow all npm test commands
• Edit(/src/*) - Allow edits to source files
• WebFetch(domain:api.github.com) - Allow GitHub API calls

Permission Pattern Examples

Patterns are automatically generated based on context:

// Bash commands → command prefix patterns
"Bash(npm run:*)"      // All npm run scripts
"Bash(git:*)"          // All git commands
"Bash(curl:*)"         // All curl requests

// Web requests → domain patterns
"WebFetch(domain:api.example.com)"   // Specific API
"WebFetch(domain:*.example.com)"     // Subdomains

// File operations → path patterns
"Edit(/src/*)"         // All files in src/
"Write(/tests/*)"      // All test files
"MultiEdit(/config/*)" // Multi-file edits in config/

📱 Multi-Session Support

Session Identification

Each Telegram message includes:

• 📁 Project: Derived from working directory
• 🔖 Session ID: Short unique identifier
• ⏰ Timestamp: When request was made

Example message:

[my-project] [sess-a1b2] 
Claude requests: Edit server.js

[Approve] [Deny] [Allow All] [Ask Claude UI]

Reply Routing

• Native Reply: Always routes to the original session
• Plain Message: Routes to the most recent session
• Multiple Projects: Each maintains independent state

🔧 Troubleshooting

No Telegram messages?

afk status          # Check if remote mode is enabled
afk telegram test   # Test connection

Buttons not working?

• Only run one AFK instance at a time
• Verify your Telegram bot has message permissions

🚀 Advanced Features

Timeout Configuration

Control what happens when approvals timeout:

{
  "timeout_seconds": 3600,     // 1 hour
  "timeout_action": "deny"     // Auto-deny on timeout
}

Timeout Actions:

• "deny": Safe default, blocks operation
• "allow": Convenient but less secure
• "wait": Never timeout, wait indefinitely

Blocking Stop Events

Enable interactive follow-ups after Claude finishes:

# In your Stop hook configuration, AFK automatically waits for user input
# Users can then reply with follow-up instructions or tap [Continue]

Installation Scopes

# Global (all projects)
afk install --scope user

# Project-specific 
afk install --scope project

# Local development
afk install --scope local

📦 Installation

Requirements: Node.js ≥ 18, Claude Code, Telegram account

Install Methods

🌟 Recommended: npm Global

npm install -g @probelabs/afk

🔧 From Source

git clone https://github.com/probelabs/afk.git
cd afk
npm link  # Creates global symlink

📄 License

MIT License - Part of the Probe Labs ecosystem

🔗 Links

📖 Documentation • 🐛 Issues • 💬 Discussions