claude-code-telegram-gateway 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hacctarr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# Claude Code Multi-Session Telegram Gateway (macOS)
+
+A private, local-first gateway that connects your **iPhone** to the **Claude Code sessions running on your Mac** over **Telegram Forum Topics**. It works in both directions:
+
+- **Desk → phone (live mirror):** run Claude normally in the native TUI on your Mac; every *active* session automatically gets its own Telegram topic, and the conversation (your desk input, Claude's replies, tool activity) mirrors into it within ~2s.
+- **Phone → desk (inject):** reply inside a topic to steer that session. When the desk session is idle, your message runs headlessly and streams back live. This is ideal when you're **away from the desk**.
+
+It is a transcript **watcher**, not a terminal scraper — it reads Claude's own session logs (`~/.claude/projects/**/<uuid>.jsonl`) and drives turns via headless `claude -p`. No `node-pty`, no ANSI parsing. Zero runtime dependencies.
+
+---
+
+## How it works
+
+```
+   ~/.claude/projects/<repo>/<uuid>.jsonl  (written by the native Claude TUI)
+                    |
+      [poll loop, every ~2s]
+        ├─ active + no topic  → createForumTopic + opener      (auto-initiate)
+        ├─ new transcript lines → mirror to the topic          (🖥️ desk / assistant / 🔧 tool)
+        └─ idle 7 days        → closeForumTopic                 (prune)
+                    ▲
+  reply in a topic → idle? → claude -p --resume (streams back) │ busy? → queue, run when idle
+  /new <msg>       → new topic + independent session
+```
+
+- **1 supergroup per repo** (`REPO_MAPPINGS`), **1 topic per session**, isolated end-to-end.
+- A session's `cwd` (stored in its transcript) maps it to the right supergroup automatically.
+- Session ↔ topic links persist in `links.json`, so topics survive restarts. `sessions.json` from
+  older versions is migrated automatically on first run.
+
+---
+
+## Prerequisites
+
+- **macOS** with Node.js 18+ (tested on v26).
+- **Claude Code CLI** installed and logged in (`claude` on your PATH).
+- A Telegram bot that is a **group Admin with the "Manage Topics" permission** (required so the
+  gateway can create/close topics). Without it, mirroring is skipped and you fall back to manually
+  creating topics + `/resume`.
+
+---
+
+## Quick start
+
+```bash
+git clone https://github.com/hacctarr/claude-code-telegram-gateway
+cd claude-code-telegram-gateway
+npm run setup          # interactive: validates your bot, auto-detects your
+                       # user id + group chat id, writes config.json, and can
+                       # install the background service for you
+```
+
+First create the bot + group (Telegram side) as in **[SETUP.md](SETUP.md)** — it takes ~2 minutes —
+then `npm run setup` does the rest. Everything below is the manual equivalent.
+
+## Setup (manual)
+
+1. **Create a bot** via `@BotFather` (`/newbot`) and copy the HTTP API token.
+2. **Create a Supergroup** per repo, enable **Topics**, add the bot, and promote it to
+   **Admin → Manage Topics + Post Messages**.
+3. **Get IDs:** your numeric user id (`@userinfobot`) and the group chat id (`-100…`, via the
+   `getUpdates` URL in [SETUP.md](SETUP.md)).
+4. **Configure:** `cp config.example.json config.json` and fill it in:
+   ```json
+   {
+     "BOT_TOKEN": "…",
+     "ALLOWED_USER_IDS": ["<your_user_id>"],
+     "REPO_MAPPINGS": { "-1001654782309": "/Users/you/Documents" },
+     "CLAUDE_PATH": "/Users/you/.nvm/versions/node/vXX/bin/claude"
+   }
+   ```
+   Optional keys (defaults shown): `MIRROR` (true), `AUTO_CREATE_TOPICS` (true),
+   `SHOW_TOOL_ACTIVITY` (true), `PERMISSION_MODE` ("bypassPermissions"), `MODEL`,
+   `IDLE_INJECT_SECONDS` (15), `ACTIVE_WINDOW_MIN` (30), `PRUNE_AFTER_DAYS` (7),
+   `PRUNE_MODE` ("close" | "delete"), `POLL_MS` (2000).
+
+> **Permissions — two ways to run it:**
+> - **`bypassPermissions`** (default): phone-injected turns run tools without prompts. Anyone
+>   allowed to post in the group gets unattended tool access to that repo — `ALLOWED_USER_IDS` is
+>   what protects it.
+> - **Any stricter mode** (e.g. `"PERMISSION_MODE": "acceptEdits"` or `"manual"`): tool-permission
+>   prompts appear **in the Telegram topic as ✅ Allow / ❌ Deny buttons** — tap to approve from your
+>   phone (only `ALLOWED_USER_IDS` presses are honored). Unanswered requests deny after
+>   `APPROVAL_TIMEOUT_SECONDS` (default 300) so turns can't hang. Your configured allow/deny rules
+>   still apply first; buttons appear only for what would genuinely prompt.
+
+---
+
+## Run
+
+Foreground (for testing):
+```bash
+npm start
+```
+
+As a background service (auto-start on login, auto-restart on crash):
+```bash
+./install-service.sh      # loads a launchd agent, logs to gateway.log, adds a `cr` alias
+tail -f gateway.log       # watch it live
+./uninstall-service.sh    # stop + remove
+```
+
+`npm test` runs the unit suite (no network, no `claude` spawn).
+
+---
+
+## Using it
+
+- **From the Mac:** just run `claude` in a mapped repo. Within ~30 min of activity a topic appears
+  on your phone and mirrors the session live.
+- **From the phone:**
+  - Reply in a topic to steer that session (runs when the desk session is idle).
+  - `/new <message>` — start a brand-new, independent session in its own topic.
+  - `/new` (bare) — detach the current topic so your next message starts a fresh session there.
+  - `/exit` (or `/close`) — close this topic and stop mirroring its session. The session stays
+    resumable on disk, and fresh desk activity re-opens a topic for it automatically.
+  - **`/desk`** — open this topic's session in the editor on your Mac (VS Code by default). The
+    clean "hand it back to the desk" move: it opens the exact session so you continue there.
+  - `/sessions` — list recent sessions in the repo.
+  - `/resume <uuid | text>` — link this topic to an existing session (searches first message + content).
+- **Back at the desk:** two ways, pick per moment —
+  - **VS Code / editor:** tap **`/desk`** in the topic; the exact session opens in your editor on the
+    Mac via a `vscode://` deep link (configurable for Cursor/Windsurf via `DESK_URL_TEMPLATE`).
+  - **Terminal:** just open one — an auto-resume hook (installed into `~/.zshrc`) drops you into that
+    branch, multi-repo aware, then clears itself. `cr` remains as a manual resume.
+
+### Phone continuation — works whether or not the desk session is closed
+- **Desk session closed:** your phone reply continues the *same* session and is saved — seamless,
+  and `cr` at the Mac picks it right up.
+- **Desk session left open:** the desk process owns the transcript, so a plain resume wouldn't
+  persist. With `AUTO_FORK` (default on) the gateway instead **forks a saved phone branch** and the
+  topic follows it — full context kept, one-line notice posted, desk copy untouched. If you later
+  keep working the desk copy, it earns its own topic automatically. Three safeguards make this
+  race-free (each was a real bug once):
+  - held-detection runs **before** the turn (`lsof`, excluding the gateway's own pid) — the prompt
+    and its tool side effects execute exactly once, and idle-but-open sessions aren't re-forked;
+  - the fork's session id is **pre-minted and reserved**, so the poller can never create a
+    duplicate topic for the branch mid-turn;
+  - a reply resolves its target session **when it runs**, so back-to-back messages follow the
+    first one's fork instead of forking the original twice.
+  Set `AUTO_FORK: false` to disable; held-session replies then run with full context but aren't
+  persisted (and say so).
+
+### Other notes
+- Mirror latency ≈ `POLL_MS` (~2s); it posts completed turns, not token-by-token (phone-injected
+  turns *do* stream token-by-token via the live-edited message). Failing desk tool calls are
+  surfaced as `⚠️ tool error`; successful tool output is kept quiet.
+- **Stall/approval notices:** a desk permission prompt is editor-UI state and never appears in the
+  transcript — from the phone the session just looks stuck. If a desk tool call stays unresolved
+  past `STALL_NOTICE_SECONDS` (default 60, 0 = off), the topic gets a one-time notice naming the
+  tool ("may be running long — or waiting for approval at the desk"), and a follow-up when it
+  completes. Approval itself must happen at the desk; `/desk` jumps you there.
+- With `bypassPermissions` (default), phone-injected turns never block on a tool-permission prompt.
+  A clarifying question in Claude's reply just streams to you; answer in the topic to continue.
+- A single-instance lock prevents two gateways from fighting over `getUpdates`. Linux users: a
+  `systemd --user` unit is in `systemd/` (macOS uses the bundled launchd installer).

package/SETUP.md

@@ -0,0 +1,75 @@
+# Telegram Setup Guide
+
+Complete steps to configure Telegram for the Claude Code gateway. The gateway connects your phone
+to the Claude Code sessions running on your Mac: active desk sessions **auto-appear as Telegram
+topics and mirror live**, and you can **reply from your phone** to steer a session when it's idle.
+
+> One bot + one supergroup per repository, per Mac. Each Forum Topic is one Claude session.
+
+---
+
+## Step 1 — Create a bot
+
+1. In Telegram, open **@BotFather** → send `/newbot`.
+2. Give it a **name** (e.g. `My Mac Claude`) and a **username ending in `bot`** (e.g. `mymac_claude_bot`).
+3. Copy the **HTTP API token** (looks like `123456789:AAH...`). You'll put it in `config.json`.
+
+> **Privacy mode:** you do **not** need to disable it. The bot must be a group **admin** (Step 2),
+> and admins receive all messages regardless of privacy mode.
+
+## Step 2 — Create the supergroup with Topics
+
+1. **New Group** → add your bot → name it after the repo (e.g. `Mac1: auth-service`).
+2. **Enable Topics:** Group Info → Edit → turn on **Topics** (this converts the group to a supergroup).
+3. **Promote the bot to Admin** (Group Info → Edit → Administrators) with **Manage Topics** and
+   **Post Messages** enabled. *This is required* — the gateway creates/closes topics via the bot.
+
+## Step 3 — Get your IDs
+
+- **Your user ID** (the security allowlist): message **@userinfobot**, copy the number → goes in
+  `ALLOWED_USER_IDS`.
+- **Group chat ID:** post any message in the group's **General** topic, then open in a browser:
+  `https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates`
+  Find the `"chat": { "id": -100... }` value (a negative number starting `-100`) → the key in
+  `REPO_MAPPINGS`.
+
+## Step 4 — Configure
+
+```bash
+cp config.example.json config.json
+```
+```json
+{
+  "BOT_TOKEN": "123456789:AAH...",
+  "ALLOWED_USER_IDS": ["<your_user_id>"],
+  "REPO_MAPPINGS": { "-1001234567890": "/Users/you/projects/auth-service" },
+  "CLAUDE_PATH": "/Users/you/.nvm/versions/node/vXX/bin/claude"
+}
+```
+`config.json` is gitignored — your token stays local. Optional tuning keys (mirror/prune/idle
+timings) are listed in `config.example.json`.
+
+Run `node test/check-telegram.js` to verify the bot's identity and that it can create/delete a
+topic (self-cleaning). Expect `✅ All checks passed`.
+
+## Step 5 — Run
+
+```bash
+npm start                 # foreground (testing)
+# or run it as a background service:
+./install-service.sh      # launchd: auto-start on login, restart on crash, logs to gateway.log
+```
+
+## Using it
+
+- **From the Mac:** run `claude` in a mapped repo. Within ~30 min of activity a topic appears on your
+  phone and mirrors the session (🖥️ desk / assistant / 🔧 tool) within ~2s.
+- **From the phone:**
+  - Reply in a topic to steer that session (runs when the desk session is idle).
+  - `/new <message>` — start a fresh, independent session in its own topic.
+  - `/sessions` — list recent sessions; `/resume <id | text>` — link a topic to an existing session.
+- **Back at the desk:** `cr` (installed alias for `claude -c`) resumes the most recent session,
+  including turns you sent from the phone.
+
+See the main [README](README.md) for the architecture and the known limitations of the
+"native TUI primary" model.

package/bin/claude-tg.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+'use strict';
+// Thin CLI so the package works via `npx claude-code-telegram-gateway <cmd>` or a global install.
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const ROOT = path.join(__dirname, '..');
+const run = (file, args = []) => execFileSync(file, args, { cwd: ROOT, stdio: 'inherit' });
+const node = (rel) => run(process.execPath, [path.join(ROOT, rel)]);
+
+const cmd = process.argv[2];
+try {
+  switch (cmd) {
+    case 'setup': node('setup.js'); break;
+    case 'start': node('gateway.js'); break;
+    case 'check': node('test/check-telegram.js'); break;
+    case 'install': case 'install-service': run(path.join(ROOT, 'install-service.sh')); break;
+    case 'uninstall': case 'uninstall-service': run(path.join(ROOT, 'uninstall-service.sh')); break;
+    default:
+      console.log(`claude-tg <command>
+
+  setup       interactive config (bot token, your id, group→repo mappings)
+  start       run the gateway in the foreground
+  check       verify the bot's Telegram permissions
+  install     install as a launchd background service (auto-start + restart)
+  uninstall   stop and remove the service`);
+  }
+} catch (e) {
+  process.exit(e.status || 1);
+}

package/com.claude.telegram-gateway.plist

@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  launchd service for the Claude Code Telegram gateway.
+  Placeholders __NODE__, __DIR__, __PATH__ are filled in by install-service.sh.
+  Do not edit the installed copy at ~/Library/LaunchAgents directly — re-run the installer.
+-->
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.claude.telegram-gateway</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>__NODE__</string>
+        <string>__DIR__/gateway.js</string>
+    </array>
+
+    <key>WorkingDirectory</key>
+    <string>__DIR__</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>__PATH__</string>
+        <key>HOME</key>
+        <string>__HOME__</string>
+    </dict>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <dict>
+        <key>SuccessfulExit</key>
+        <false/>
+        <key>Crashed</key>
+        <true/>
+    </dict>
+
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+
+    <key>StandardOutPath</key>
+    <string>__DIR__/gateway.log</string>
+    <key>StandardErrorPath</key>
+    <string>__DIR__/gateway.log</string>
+</dict>
+</plist>

package/config.example.json

@@ -0,0 +1,29 @@
+{
+  "BOT_TOKEN": "123456789:AAHfiqksKZ8...",
+  "ALLOWED_USER_IDS": [
+    "412587349"
+  ],
+  "REPO_MAPPINGS": {
+    "-1001654782309": "/Users/you/projects/auth-service",
+    "-1001987654321": "/Users/you/projects/frontend-ui"
+  },
+  "CLAUDE_PATH": "/Users/you/.nvm/versions/node/v26.2.0/bin/claude",
+  "PERMISSION_MODE": "bypassPermissions",
+  "MODEL": "opus",
+  "MIRROR": true,
+  "AUTO_CREATE_TOPICS": true,
+  "SHOW_TOOL_ACTIVITY": true,
+  "IDLE_INJECT_SECONDS": 15,
+  "ACTIVE_WINDOW_MIN": 30,
+  "PRUNE_AFTER_DAYS": 7,
+  "PRUNE_MODE": "close",
+  "POLL_MS": 2000,
+  "MIRROR_FLUSH_MS": 4000,
+  "DESK_URL_TEMPLATE": "vscode://anthropic.claude-code/open?session={session}",
+  "DESK_OPEN_CMD": "open",
+  "TITLE_MODE": "generated",
+  "TITLE_MODEL": "haiku",
+  "AUTO_FORK": true,
+  "STALL_NOTICE_SECONDS": 60,
+  "APPROVAL_TIMEOUT_SECONDS": 300
+}