afk-claude-telegram-bridge

Files (93)

• .gitignore
• pre-commit · .husky/
• pre-push · .husky/
• AGENTS.md
• ARCHITECTURE.md
• CHANGELOG.md
• CLAUDE.md
• LICENSE
• README.md
• SKILL.md
• build.mjs
• config.json
• bridge.js · dist/
• cli.js · dist/
• hook.js · dist/
• 2026-02-22-session-isolation-design.md · docs/plans/
• 2026-02-23-session-resilience-context-mgmt-design.md · docs/plans/
• 2026-02-23-session-resilience-impl-plan.md · docs/plans/
• 2026-02-25-afk-ux-improvements-design.md · docs/plans/
• 2026-02-25-afk-ux-improvements-impl-plan.md · docs/plans/
• 2026-02-26-phase2-tasks4-6-design.md · docs/plans/
• 2026-02-26-phase2-tasks4-6-implementation.md · docs/plans/
• 2026-02-26-phases3-5-dual-deployment-design.md · docs/plans/
• 2026-02-26-phases3-5-implementation.md · docs/plans/
• 2026-02-26-ts-rewrite-design.md · docs/plans/
• 2026-02-26-ts-rewrite-impl-plan-v2-fp-corrected.md · docs/plans/
• 2026-02-26-ts-rewrite-impl-plan.md · docs/plans/
• 2026-02-27-ts-activate-deactivate-design.md · docs/plans/
• 2026-02-27-ts-activate-deactivate.md · docs/plans/
• 2026-03-03-sqlite-ipc-design.md · docs/plans/
• 2026-03-03-sqlite-ipc-implementation.md · docs/plans/
• 2026-03-12-node-sqlite-migration-design.md · docs/plans/
• 2026-03-12-node-sqlite-migration-impl.md · docs/plans/
• install.sh
• jest.config.js
• package-lock.json
• package.json
• hook-wrapper.sh · scripts/
• e2e-active-listening.test.ts · src/__tests__/
• e2e-sqlite-permission.test.ts · src/__tests__/
• e2e-sqlite-stop.test.ts · src/__tests__/
• fixtures.ts · src/__tests__/helpers/
• mockFs.ts · src/__tests__/helpers/
• mockTelegram.ts · src/__tests__/helpers/
• daemon.test.ts · src/bridge/__tests__/
• daemon.ts · src/bridge/
• activate.ts · src/cli/
• deactivate.ts · src/cli/
• index.ts · src/cli/
• index.test.ts · src/core/config/__tests__/
• index.ts · src/core/config/
• index.test.ts · src/core/state/__tests__/
• index.ts · src/core/state/
• args.test.ts · src/hook/__tests__/
• index.test.ts · src/hook/__tests__/
• permission.test.ts · src/hook/__tests__/
• stop.test.ts · src/hook/__tests__/
• args.ts · src/hook/
• index.ts · src/hook/
• permission.ts · src/hook/
• …and 33 more

SKILL.md (first lines)

# AFK Claude Telegram Bridge

Remote-control Claude Code sessions from your phone via Telegram when AFK (away from keyboard).

## When to Use

- "set up telegram bridge" / "configure telegram AFK"
- "enable remote control" / "activate AFK mode"
- "I want to control Claude from my phone"
- Installing this skill on a new machine

## What This Skill Does

Installs a complete Telegram ↔ Claude Code bridge that allows you to:

1. **Approve/deny tool calls** from Telegram inline keyboards
2. **Continue tasks** by sending new instructions when Claude finishes
3. **Auto-approve** read-only tools (Read, Glob, Grep, WebSearch, WebFetch)
4. **Multi-session support** — up to 4 concurrent sessions (S1-S4)
5. **Zero native dependencies** — uses Node.js built-in `node:sqlite` for session state and IPC (no native addons to compile)

## Installation

Install via curl (recommended):

```bash
curl -fsSL https://raw.githubusercontent.com/gmotyl/afk-claude-telegram-bridge/main/install.sh | bash
```

Or from a local clone:

```bash
git clone https://github.com/gmotyl/afk-claude-telegram-bridge.git
cd afk-claude-telegram-bridge
npm install && npm run deploy
```

The installer downloads pre-built binaries from GitHub and handles everything:
- Copies hook.js, bridge.js, cli.js, hook.sh to `~/.claude/hooks/telegram-bridge/`
- Installs `/afk`, `/back`, and `/afk-reset` commands to `~/.claude/commands/`
- Registers Stop, Notification, and PreToolUse hooks in `~/.claude/settings.json`
- Prompts for your bot token and auto-detects your Telegram group

**Restart Claude Code after installation** to load the new commands.

### Prerequisites

Before running the installer, create a Telegram bot:

1. Open Telegram -> search **@BotFather** -> send `/newbot`
2. Name it "Claude Bridge" (or your preferred name)
3. Copy the bot token
4. Create a **Telegram Group** with **Topics enabled**
5. Add the bot to the group as **Administrator**
6. Send a message in the group (so the bot can detect it)

## Usage

### Activate AFK Mode

In any Claude Code session:
```
/afk
```

You'll see a confirmation on Telegram: "📡 S1 — AFK Activated"

### Deactivate AFK Mode

```
/back
```

### From Telegram

When Claude needs approval for a tool call, you'll see:
```
🔐 S1 — Permission Request
Tool: Bash
`npm install express`
[✅ Approve] [❌ Deny]
```

When Claude finishes a task:
```
✅ S1 — Task Complete
I've implemented the login form...
[🛑 Let it stop]
```

Reply with text to send Claude a new instruction!

### Multi-Session

With multiple sessions, prefix instructions:
```
S1: now add unit tests
S2: push to remote
```

## File Structure

After installation:
```
~/.claude/hooks/telegram-bridge/
  hook.sh        — Bash wrapper (Claude Code calls this)
  hook.js        — Compiled hook entry point (Node.js)
  bridge.js      — Compiled Telegram daemon (Node.js)
  config.json    — Bot token, group ID, settings
  bridge.db      — SQLite database (sessions, events, state)
  active_count   — Marker file for fast bash gate check
  daemon.log     — Daemon log

~/.claude/commands/
  afk.md         — /afk command
  back.md        — /back command
  afk-reset.md   — /afk-reset command
```

From gmotyl/afk-claude-telegram-bridge-skill, MIT.

More from gmotyl/afk-claude-telegram-bridge-skill