https://github.com/probelabs/afk
Remote control and approval system for Claude Code via Telegram. Zero dependencies, Node.js 18+ built-ins only.
https://github.com/probelabs/afk
afk approval-system claude-code cli nodejs remote-control telegram-bot zero-dependencies
Last synced: about 1 month ago
JSON representation
Remote control and approval system for Claude Code via Telegram. Zero dependencies, Node.js 18+ built-ins only.
- Host: GitHub
- URL: https://github.com/probelabs/afk
- Owner: probelabs
- License: mit
- Created: 2025-08-28T10:10:13.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2025-09-03T10:49:27.000Z (about 1 month ago)
- Last Synced: 2025-09-04T00:01:54.927Z (about 1 month ago)
- Topics: afk, approval-system, claude-code, cli, nodejs, remote-control, telegram-bot, zero-dependencies
- Language: JavaScript
- Size: 273 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# AFK - Control Claude Code from Anywhere
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](package.json)
[](https://www.npmjs.com/package/@probelabs/afk)
> **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:
```bash
# 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
```bash
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
```bash
afk setup # Interactive Telegram bot setup
afk install # Install Claude Code hooks
afk uninstall # Remove hooks
```
### Testing & Debug
```bash
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:
1. 🤖 Creates your Telegram bot via @BotFather
2. 🔑 Securely stores bot token (masked input)
3. 💬 Auto-detects your chat ID
4. ✅ Tests the connection
5. 💾 Saves to `~/.afk/config.json`
**Config file:**
```json
{
"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
```bash
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:**
1. Check Claude's existing permissions → Use those if set
2. Check auto-approve list → Safe tools go through automatically
3. Check mode → Local uses Claude UI, Remote sends to Telegram
4. 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:
```javascript
// 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?**
```bash
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:
```json
{
"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:
```bash
# In your Stop hook configuration, AFK automatically waits for user input
# Users can then reply with follow-up instructions or tap [Continue]
```
### Installation Scopes
```bash
# 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**
```bash
npm install -g @probelabs/afk
```
#### 🔧 **From Source**
```bash
git clone https://github.com/probelabs/afk.git
cd afk
npm link # Creates global symlink
```
## 📄 License
MIT License - Part of the [Probe Labs](https://probelabs.com) ecosystem
## 🔗 Links
📖 [Documentation](https://probelabs.com/afk) • 🐛 [Issues](https://github.com/probelabs/afk/issues) • 💬 [Discussions](https://github.com/probelabs/afk/discussions)