{"id":30685626,"url":"https://github.com/probelabs/afk","last_synced_at":"2026-03-07T03:31:17.779Z","repository":{"id":312068950,"uuid":"1046185100","full_name":"probelabs/afk","owner":"probelabs","description":"Remote control and approval system for Claude Code via Telegram. Zero dependencies, Node.js 18+ built-ins only.","archived":false,"fork":false,"pushed_at":"2025-09-08T10:08:05.000Z","size":349,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-06T00:42:44.346Z","etag":null,"topics":["afk","approval-system","claude-code","cli","nodejs","remote-control","telegram-bot","zero-dependencies"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/probelabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-28T10:10:13.000Z","updated_at":"2025-09-08T10:08:09.000Z","dependencies_parsed_at":"2025-08-28T17:13:00.746Z","dependency_job_id":"152a2ee0-1268-41e7-b600-3b9ef612c208","html_url":"https://github.com/probelabs/afk","commit_stats":null,"previous_names":["probelabs/afk"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/probelabs/afk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probelabs%2Fafk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probelabs%2Fafk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probelabs%2Fafk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probelabs%2Fafk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/probelabs","download_url":"https://codeload.github.com/probelabs/afk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/probelabs%2Fafk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30206563,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T03:24:23.086Z","status":"ssl_error","status_checked_at":"2026-03-07T03:23:11.444Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["afk","approval-system","claude-code","cli","nodejs","remote-control","telegram-bot","zero-dependencies"],"created_at":"2025-09-01T22:01:35.154Z","updated_at":"2026-03-07T03:31:17.765Z","avatar_url":"https://github.com/probelabs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"site/afk-logo.png\" alt=\"AFK Logo\" width=\"200\" /\u003e\n\u003c/p\u003e\n\n# AFK - Control Claude Code from Anywhere\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node Version](https://img.shields.io/badge/node-%E2%89%A518-brightgreen.svg)](https://nodejs.org/)\n[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-blue.svg)](package.json)\n[![npm version](https://img.shields.io/npm/v/@probelabs/afk.svg)](https://www.npmjs.com/package/@probelabs/afk)\n\n\u003e **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. **Plus**: Integrate any AI system with remote approval using simple binary calls.\n\n## ⚡ Quick Start\n\n3 commands, 2 minutes, full mobile control:\n\n```bash\n# 1. Install and setup\nnpm install -g @probelabs/afk\nafk setup  # Creates your Telegram bot\n\n# 2. Go remote\nafk        # Smart toggle: installs hooks and enables remote mode\n```\n\n**That's it!** Claude Code now sends approval requests to your phone. 📱\n\n### What happens next?\n- Claude starts a task → You get a Telegram notification\n- Tap **Approve** → Claude continues\n- Tap **Deny** → Claude stops and asks for guidance\n- Step away confident your code is safe\n\n## 🎯 Why AFK?\n\n**📱 Mobile Development Freedom**\n- ☕ Step away during long refactors\n- 🚇 Approve changes from your commute  \n- 🏖️ Monitor critical tasks remotely\n- 🔒 Add approval gates for sensitive operations\n\n**🤖 Universal AI Integration**\n- Not just Claude Code—works with any AI system\n- Simple binary calls (Python, Node.js, bash, etc.)\n- [Complete integration guide](INTEGRATION.md) with examples\n- Risk assessment and approval policies\n\n**🔐 Privacy First**\n- Zero cloud dependencies\n- Direct Telegram connection\n- Your bot, your control\n- Local state only\n\n**🚀 Smart Integration**\n- Works with Claude Code's permission system\n- Multi-project session management\n- Auto-approve safe operations\n- Timeout protection\n\n## 🛠️ Commands\n\n### Basic Usage\n```bash\nafk              # Smart toggle: install if needed, then toggle mode\nafk on           # Enable remote approvals  \nafk off          # Disable remote approvals\nafk readonly     # Enable read-only mode (notifications without blocking)\nafk status       # Check current mode\n```\n\n### Claude Commands\nControl AFK mode directly from Claude Code interface:\n```bash\n/afk             # Toggle global AFK mode (local ↔ remote)\n/afk:on          # Enable remote mode globally\n/afk:off         # Disable remote mode globally\n/afk:readonly    # Enable read-only mode globally\n/afk:status      # Show current mode status\n/afk:global      # Toggle global mode (same as /afk)\n/afk:project     # Toggle project-specific mode\n/afk:help        # Show command help\n```\n\n### Setup \u0026 Installation\n```bash\nafk setup        # Interactive Telegram bot setup\nafk install      # Install Claude Code hooks\nafk uninstall    # Remove hooks\n```\n\n### Testing \u0026 Debug\n```bash\nafk telegram test    # Test Telegram connection\nafk debug on         # Enable debug logging\n```\n\n## 🎛️ Operating Modes\n\nAFK supports three operating modes to fit different workflows:\n\n### 🔒 Remote Mode (`afk on`)\n- **Full approval workflow**: All permissioned tools require Telegram approval\n- **Interactive**: Tap Approve/Deny buttons for each action\n- **Blocking**: Claude waits for your response before proceeding\n- **Best for**: Active development when you want full control\n\n### 🏠 Local Mode (`afk off`) \n- **Default Claude behavior**: Uses Claude's built-in permission prompts\n- **No Telegram notifications**: Everything happens in Claude interface\n- **Non-blocking**: Normal Claude workflow\n- **Best for**: When working directly at your computer\n\n### 📖 Read-Only Mode (`afk readonly`)\n- **Passive monitoring**: Get notified of completed sessions\n- **No approvals required**: Tools execute without intervention\n- **Non-blocking**: No delays or waiting\n- **Best for**: Monitoring long-running tasks without interference\n\n**Mode Toggle Behavior:**\n- `afk` or `afk toggle`: Cycles between Local ↔ Remote only\n- `afk readonly`: Explicit command to enable read-only mode\n- Read-only mode is separate and doesn't interfere with normal toggling\n\n## 🤖 AI Integration\n\n**Want to integrate AFK with your own AI system?** Check out our [comprehensive integration guide](INTEGRATION.md) with examples for:\n\n- 🐍 **Python**: Simple AFKIntegration class with subprocess calls\n- 🚀 **Node.js**: Promise-based integration with error handling  \n- 🔧 **Bash**: Pure shell script integration with JSON piping\n- 🎯 **Generic Template**: Complete framework with risk assessment\n\n**Quick Example (Python):**\n```python\nfrom afk_integration import AFKIntegration\n\nafk = AFKIntegration(\"my-ai-session\")\nif afk.request_approval(\"execute_code\", {\"code\": \"print('Hello!')\", \"language\": \"python\"}):\n    exec(\"print('Hello!')\")  # User approved - execute\nelse:\n    print(\"User denied code execution\")\n```\n\n**Setup Integration Examples:**\n```bash\n# Run the setup script to install AFK and configure examples\nbash scripts/setup-integration.sh\n\n# Test all integration examples\nbash scripts/test-integration.sh\n```\n\n## 🔧 How it Works\n\n**1. Hook Integration**\nAFK hooks into Claude Code at key decision points:\n- **PreToolUse**: Intercepts risky operations (file edits, bash commands, web requests)\n- **SessionStart**: Notifies when new coding sessions begin  \n- **Stop**: Enables follow-up conversations when tasks complete\n\n**2. Smart Permissions**\n- Respects Claude's existing allow/deny lists\n- Auto-approves safe tools like `Read` and `Grep`\n- Creates permanent patterns from one-time approvals\n\n**3. Mode-Based Workflow**\n```\nClaude wants to edit file.js\n        ↓\nAFK checks current mode:\n        ↓\nLocal Mode: Claude handles normally\nRemote Mode: Send approval request → Wait for response\nRead-Only Mode: Allow execution, notify on completion\n        ↓\nYou tap: [Approve] [Deny] [Allow All] [Ask Claude UI] (Remote only)\n        ↓\nClaude proceeds based on mode and your choice\n```\n\n**4. Session Management**\n- Each Claude session gets unique ID\n- Messages tagged with project and session\n- Reply threading maintains conversation context\n\n## 🏗️ Architecture\n\n### System Overview\n\n```\n┌──────────────────┐         ┌──────────────────┐         ┌──────────────────┐\n│                  │         │                  │         │                  │\n│   Claude Code    │────────▶│   AFK Hooks      │────────▶│   Telegram API   │\n│                  │         │                  │         │                  │\n│  • PreToolUse    │         │ • Intercepts     │         │ • Distributed    │\n│  • SessionStart  │         │ • Routes msgs    │         │   polling        │\n│  • Stop events   │◀────────│ • Manages state  │◀────────│ • Button handling│\n│  • Notifications │         │                  │         │                  │\n└──────────────────┘         └──────────────────┘         └──────────────────┘\n        ▲                            │                            \n        │                            │                            \n        │                            ▼                            \n        │                    ┌──────────────────┐                \n        │                    │                  │                \n        └────────────────────│   Local State    │                \n                             │                  │                \n                             │ • ~/.afk         │               \n                             │ • Mode (on/off)  │               \n                             │ • Session map    │               \n                             │ • Approvals      │               \n                             └──────────────────┘               \n```\n\n### Hook Integration Points\n\n**PreToolUse Hook** - Gates tool execution:\n- Checks current mode (local/remote)\n- Validates against Claude's existing permissions\n- Sends approval requests to Telegram in remote mode\n- Waits for user response with timeout\n\n**SessionStart Hook** - New session notifications:\n- Notifies when Claude begins new coding sessions\n- Waits for initial instructions or \"Continue\" \n- Can inject follow-up tasks via process exit code 2\n\n**Stop Hook** - Task completion handling:\n- Sends completion notifications to Telegram\n- Enables follow-up conversations and instructions\n- Supports session continuation or closure\n\n## ⚙️ Configuration\n\nRun `afk setup` for interactive configuration. The wizard:\n\n1. 🤖 Creates your Telegram bot via @BotFather\n2. 🔑 Securely stores bot token (masked input)\n3. 💬 Auto-detects your chat ID  \n4. ✅ Tests the connection\n5. 💾 Saves to `~/.afk/config.json`\n\n**Config file:**\n```json\n{\n  \"telegram_bot_token\": \"YOUR_BOT_TOKEN\",\n  \"telegram_chat_id\": \"YOUR_CHAT_ID\",\n  \"timeout_seconds\": 3600,\n  \"intercept_matcher\": \"Bash|Edit|Write|MultiEdit|WebFetch|mcp__.*\",\n  \"auto_approve_tools\": [\"Read\"]\n}\n```\n\n### Configuration Options\n\n| Option | Description | Default | Options |\n|--------|-------------|---------|---------|\n| `timeout_seconds` | Approval timeout | `3600` (1 hour) | Any positive number, `0` for infinite |\n| `intercept_matcher` | Tools to intercept | `\"Bash\\|Edit\\|Write\\|MultiEdit\\|WebFetch\\|mcp__.*\"` | Regex pattern |\n| `auto_approve_tools` | Always allow these | `[\"Read\"]` | Array of tool names |\n\n**Note**: Additional options like `timeout_action` and `respect_claude_permissions` can be added manually to the config file if needed.\n\n### Environment Variables\n\n```bash\nexport TELEGRAM_BOT_TOKEN=\"your_token\"    # Alternative to config file\nexport TELEGRAM_CHAT_ID=\"your_chat_id\"    # Alternative to config file\nexport CC_REMOTE_STOP_TIMEOUT=21600       # Stop event timeout (6 hours)\n```\n\n## 🔐 Smart Approval System\n\n**Permission Flow:**\n1. Check Claude's existing permissions → Use those if set\n2. Check auto-approve list → Safe tools go through automatically  \n3. Check mode → Local uses Claude UI, Remote sends to Telegram\n4. Telegram approval → Tap **[Approve]**, **[Deny]**, **[Allow All]**, or **[Ask Claude UI]**\n\n**Smart Patterns:**\nWhen you tap **[Allow All]**, AFK creates permanent rules like:\n- `Bash(npm test:*)` - Allow all npm test commands\n- `Edit(/src/*)` - Allow edits to source files\n- `WebFetch(domain:api.github.com)` - Allow GitHub API calls\n\n### Permission Pattern Examples\n\nPatterns are automatically generated based on context:\n\n```javascript\n// Bash commands → command prefix patterns\n\"Bash(npm run:*)\"      // All npm run scripts\n\"Bash(git:*)\"          // All git commands\n\"Bash(curl:*)\"         // All curl requests\n\n// Web requests → domain patterns\n\"WebFetch(domain:api.example.com)\"   // Specific API\n\"WebFetch(domain:*.example.com)\"     // Subdomains\n\n// File operations → path patterns\n\"Edit(/src/*)\"         // All files in src/\n\"Write(/tests/*)\"      // All test files\n\"MultiEdit(/config/*)\" // Multi-file edits in config/\n```\n\n## 📱 Multi-Session Support\n\n### Session Identification\n\nEach Telegram message includes:\n- 📁 **Project**: Derived from working directory\n- 🔖 **Session ID**: Short unique identifier  \n- ⏰ **Timestamp**: When request was made\n\nExample message:\n```\n[my-project] [sess-a1b2] \nClaude requests: Edit server.js\n\n[Approve] [Deny] [Allow All] [Ask Claude UI]\n```\n\n### Reply Routing\n- **Native Reply**: Always routes to the original session\n- **Plain Message**: Routes to the most recent session\n- **Multiple Projects**: Each maintains independent state\n\n## 🔧 Troubleshooting\n\n**No Telegram messages?**\n```bash\nafk status          # Check if remote mode is enabled\nafk telegram test   # Test connection\n```\n\n**Buttons not working?**\n- Only run one AFK instance at a time\n- Verify your Telegram bot has message permissions\n\n## 🚀 Advanced Features\n\n### Timeout Configuration\nControl what happens when approvals timeout:\n\n```json\n{\n  \"timeout_seconds\": 3600,     // 1 hour\n  \"timeout_action\": \"deny\"     // Auto-deny on timeout\n}\n```\n\n**Timeout Actions:**\n- `\"deny\"`: Safe default, blocks operation\n- `\"allow\"`: Convenient but less secure\n- `\"wait\"`: Never timeout, wait indefinitely\n\n### Blocking Stop Events\nEnable interactive follow-ups after Claude finishes:\n\n```bash\n# In your Stop hook configuration, AFK automatically waits for user input\n# Users can then reply with follow-up instructions or tap [Continue]\n```\n\n### Installation Scopes\n```bash\n# Global (all projects)\nafk install --scope user\n\n# Project-specific \nafk install --scope project\n\n# Local development\nafk install --scope local\n```\n\n---\n\n## 📦 Installation\n\n**Requirements:** Node.js ≥ 18, Claude Code, Telegram account\n\n### Install Methods\n\n#### 🌟 **Recommended: npm Global**\n```bash\nnpm install -g @probelabs/afk\n```\n\n#### 🔧 **From Source**\n```bash\ngit clone https://github.com/probelabs/afk.git\ncd afk\nnpm link  # Creates global symlink\n```\n\n## 📄 License\n\nMIT License - Part of the [Probe Labs](https://probelabs.com) ecosystem\n\n## 🔗 Links\n\n📖 [Documentation](https://probelabs.com/afk) • 🤖 [AI Integration Guide](INTEGRATION.md) • 🐛 [Issues](https://github.com/probelabs/afk/issues) • 💬 [Discussions](https://github.com/probelabs/afk/discussions)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprobelabs%2Fafk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprobelabs%2Fafk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprobelabs%2Fafk/lists"}