claude-code-telegram-gateway 1.0.0

package/install-service.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Install the Claude Code Telegram gateway as a macOS launchd service (auto-start + auto-restart).
+set -euo pipefail
+
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LABEL="com.claude.telegram-gateway"
+PLIST_SRC="$DIR/$LABEL.plist"
+PLIST_DST="$HOME/Library/LaunchAgents/$LABEL.plist"
+
+NODE_BIN="$(command -v node || true)"
+if [[ -z "$NODE_BIN" ]]; then echo "❌ node not found on PATH. Install Node or fix PATH, then retry." >&2; exit 1; fi
+NODE_DIR="$(dirname "$NODE_BIN")"
+
+mkdir -p "$HOME/Library/LaunchAgents"
+
+# Fill placeholders. Use | as sed delimiter since paths contain /.
+sed -e "s|__NODE__|$NODE_BIN|g" \
+    -e "s|__DIR__|$DIR|g" \
+    -e "s|__HOME__|$HOME|g" \
+    -e "s|__PATH__|$NODE_DIR:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin|g" \
+    "$PLIST_SRC" > "$PLIST_DST"
+
+# (Re)load the service. bootout is async, so retry bootstrap a few times to dodge the
+# "Input/output error (5)" race when the old instance hasn't fully torn down yet.
+launchctl bootout "gui/$(id -u)/$LABEL" 2>/dev/null || true
+booted=0
+for _ in 1 2 3 4 5; do
+  sleep 1
+  if launchctl bootstrap "gui/$(id -u)" "$PLIST_DST" 2>/dev/null; then booted=1; break; fi
+done
+if [ "$booted" != 1 ]; then
+  echo "⚠️  launchctl bootstrap failed. Try: launchctl bootout gui/$(id -u)/$LABEL ; ./install-service.sh" >&2
+fi
+launchctl enable "gui/$(id -u)/$LABEL" 2>/dev/null || true
+launchctl kickstart "gui/$(id -u)/$LABEL" 2>/dev/null || true
+
+# Shell integration: auto-resume the branch you were working on from your phone, so opening a
+# terminal drops you straight back in — no `cr` needed (multi-repo aware). `cr` stays as a manual
+# fallback. The block is idempotent and marked so uninstall can strip it.
+RC="$HOME/.zshrc"
+if ! grep -qF 'claude-gateway auto-resume' "$RC" 2>/dev/null; then
+  cat >> "$RC" <<HOOK
+
+# >>> claude-gateway auto-resume >>>
+# On an interactive shell, resume any branch you just drove from your phone, then clear the marker.
+_claude_gateway_resume() {
+  local out; out="\$(node "$DIR/resume-hook.js" 2>/dev/null)" || return
+  [ -z "\$out" ] && return
+  local repo="\${out%%\$'\t'*}" sid="\${out##*\$'\t'}"
+  [ -d "\$repo" ] && cd "\$repo" && command claude --resume "\$sid"
+}
+alias cr='node "$DIR/resume-hook.js" >/dev/null 2>&1; claude -c'   # manual: resume most recent here
+[[ -o interactive ]] && _claude_gateway_resume
+# <<< claude-gateway auto-resume <<<
+HOOK
+  echo "🔗 Added auto-resume hook to $RC (open a new terminal to use it)."
+fi
+
+echo "✅ Installed and started $LABEL."
+echo "   Logs:   tail -f \"$DIR/gateway.log\""
+echo "   Status: launchctl print gui/$(id -u)/$LABEL | grep -i state"
+echo "   Stop:   ./uninstall-service.sh"
+echo
+echo "⚠️  For auto-topics: make the bot a group Admin with the 'Manage Topics' permission."

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "claude-code-telegram-gateway",
+  "version": "1.0.0",
+  "description": "Steer and mirror Claude Code sessions from your phone via Telegram — auto-created Forum Topics, live desk↔phone mirroring, launchd service.",
+  "main": "gateway.js",
+  "bin": {
+    "claude-tg": "bin/claude-tg.js"
+  },
+  "scripts": {
+    "setup": "node setup.js",
+    "start": "node gateway.js",
+    "check": "node test/check-telegram.js",
+    "install-service": "./install-service.sh",
+    "uninstall-service": "./uninstall-service.sh",
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "anthropic",
+    "telegram",
+    "telegram-bot",
+    "gateway",
+    "macos",
+    "launchd"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "gateway.js",
+    "setup.js",
+    "resume-hook.js",
+    "bin/",
+    "test/",
+    "install-service.sh",
+    "uninstall-service.sh",
+    "com.claude.telegram-gateway.plist",
+    "systemd/claude-gateway.service",
+    "config.example.json",
+    "README.md",
+    "SETUP.md",
+    "LICENSE"
+  ],
+  "dependencies": {},
+  "author": "hacctarr",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hacctarr/claude-code-telegram-gateway.git"
+  },
+  "homepage": "https://github.com/hacctarr/claude-code-telegram-gateway#readme",
+  "bugs": {
+    "url": "https://github.com/hacctarr/claude-code-telegram-gateway/issues"
+  }
+}

package/resume-hook.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+'use strict';
+// Prints "<repoDir>\t<sessionId>" for the newest phone-driven branch and consumes it, so a shell
+// hook can auto-resume it. Prints nothing when there's nothing pending. Multi-repo aware.
+const fs = require('fs');
+const path = require('path');
+const MARKER = path.join(process.env.HOME, '.claude-gateway', 'resume.json');
+try {
+  const m = JSON.parse(fs.readFileSync(MARKER, 'utf8'));
+  const entries = Object.entries(m).sort((a, b) => (b[1].ts || 0) - (a[1].ts || 0));
+  if (!entries.length) process.exit(0);
+  const [repo, info] = entries[0];
+  process.stdout.write(`${repo}\t${info.sessionId}`);
+  delete m[repo];
+  if (Object.keys(m).length) fs.writeFileSync(MARKER, JSON.stringify(m, null, 2));
+  else fs.unlinkSync(MARKER);
+} catch (e) { /* no marker → nothing to resume */ }

package/setup.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+'use strict';
+// Interactive setup: validates the bot, auto-detects your claude path, auto-grabs your user id and
+// group chat id from Telegram, and writes config.json. No dependencies. Run: npm run setup
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const readline = require('readline');
+const { execSync } = require('child_process');
+
+const CONFIG = path.join(__dirname, 'config.json');
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+const ask = (q) => new Promise((res) => rl.question(q, (a) => res(a.trim())));
+const yes = (s) => /^y/i.test(s);
+
+function tg(token, method, payload = {}) {
+  return new Promise((resolve) => {
+    const data = JSON.stringify(payload);
+    const req = https.request({
+      hostname: 'api.telegram.org', path: `/bot${token}/${method}`, method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data) },
+    }, (r) => { let b = ''; r.on('data', (c) => (b += c)); r.on('end', () => { try { resolve(JSON.parse(b)); } catch (e) { resolve({ ok: false }); } }); });
+    req.on('error', () => resolve({ ok: false })); req.write(data); req.end();
+  });
+}
+const expand = (p) => p.replace(/^~(?=\/|$)/, process.env.HOME);
+
+(async () => {
+  console.log('\n🤖  Claude Code Telegram Gateway — setup\n');
+
+  let cfg = {};
+  if (fs.existsSync(CONFIG)) {
+    if (!yes(await ask('config.json already exists. Update it? [y/N] '))) { console.log('Aborted.'); return rl.close(); }
+    try { cfg = JSON.parse(fs.readFileSync(CONFIG, 'utf8')); } catch (e) { /* */ }
+  }
+
+  // 1) Bot token (validated via getMe)
+  let token = cfg.BOT_TOKEN, me = null;
+  for (;;) {
+    const entered = await ask(`Bot token from @BotFather${token ? ` [keep ${token.slice(0, 8)}…]` : ''}: `);
+    token = entered || token;
+    if (!token) { console.log('  A token is required.'); continue; }
+    process.stdout.write('  validating… ');
+    me = await tg(token, 'getMe');
+    if (me.ok) { console.log(`✅ @${me.result.username}`); break; }
+    console.log('❌ invalid token — try again.');
+  }
+  cfg.BOT_TOKEN = token;
+  const botId = String(me.result.id);
+
+  // 2) Claude binary (auto-detected)
+  let claudePath = cfg.CLAUDE_PATH;
+  if (!claudePath) { try { claudePath = execSync('command -v claude', { shell: '/bin/bash' }).toString().trim(); } catch (e) { /* */ } }
+  const cp = await ask(`Path to the claude binary${claudePath ? ` [${claudePath}]` : ''}: `);
+  cfg.CLAUDE_PATH = cp || claudePath || 'claude';
+
+  // 3) Your user id (auto-detected via getUpdates)
+  console.log('\n👤 Your Telegram user id — the ONLY account allowed to control the bot.');
+  console.log('   Open a DM with your bot (or post in your group) and send it any message.');
+  await ask('   Press Enter once you have sent a message… ');
+  let userId = null;
+  const up1 = await tg(token, 'getUpdates', { timeout: 0 });
+  if (up1.error_code === 409) console.log('   ⚠️ The gateway service seems to be running — stop it (./uninstall-service.sh) and re-run setup for auto-detect.');
+  const senders = [...new Set((up1.result || []).map((u) => u.message && u.message.from && u.message.from.id).filter(Boolean))].filter((id) => String(id) !== botId);
+  if (senders.length === 1) { userId = String(senders[0]); console.log(`   ✅ detected user id ${userId}`); }
+  else if (senders.length > 1) { console.log('   Multiple senders:', senders.join(', ')); userId = await ask('   Which is yours? '); }
+  if (!userId) userId = await ask('   Enter your numeric user id (get it from @userinfobot): ');
+  cfg.ALLOWED_USER_IDS = userId ? [String(userId)] : (cfg.ALLOWED_USER_IDS || []);
+
+  // 4) Group → repo mappings (chat id auto-detected)
+  console.log('\n📁 Map each Telegram supergroup to a local repo directory.');
+  cfg.REPO_MAPPINGS = cfg.REPO_MAPPINGS || {};
+  for (;;) {
+    if (!yes(await ask('   Add a group → repo mapping? [Y/n] ') || 'y')) break;
+    console.log('   In that group\'s General topic, post any message.');
+    await ask('   Press Enter once posted… ');
+    const up = await tg(token, 'getUpdates', { timeout: 0 });
+    const chats = [...new Map((up.result || [])
+      .map((u) => u.message && u.message.chat)
+      .filter((c) => c && (c.type === 'supergroup' || c.type === 'group'))
+      .map((c) => [String(c.id), c])).values()];
+    let chatId;
+    if (chats.length) {
+      chats.forEach((c, i) => console.log(`     [${i + 1}] ${c.id}  ${c.title || ''}`));
+      const pick = await ask(`   Pick [1-${chats.length}] or type a chat id: `);
+      chatId = (/^-?\d+$/.test(pick) && pick.length > 3) ? pick : String((chats[(parseInt(pick, 10) || 1) - 1] || chats[0]).id);
+    } else {
+      chatId = await ask('   Couldn\'t detect a group — enter its chat id (-100…): ');
+    }
+    let dir = expand(await ask('   Local repo directory (absolute path): '));
+    if (dir && !fs.existsSync(dir) && !yes(await ask(`   ${dir} doesn't exist — use anyway? [y/N] `))) continue;
+    if (chatId && dir) { cfg.REPO_MAPPINGS[chatId] = dir; console.log(`   ✅ ${chatId} → ${dir}`); }
+  }
+
+  fs.writeFileSync(CONFIG, JSON.stringify(cfg, null, 2) + '\n');
+  console.log(`\n✅ Wrote ${CONFIG}`);
+  console.log('   (config.json is gitignored — your token stays local.)\n');
+
+  if (yes(await ask('Run the Telegram permission check now? [Y/n] ') || 'y')) {
+    try { execSync(`node ${path.join(__dirname, 'test', 'check-telegram.js')}`, { stdio: 'inherit' }); } catch (e) { /* */ }
+  }
+  if (yes(await ask('\nInstall as a background service (launchd, auto-start + restart)? [y/N] '))) {
+    try { execSync(path.join(__dirname, 'install-service.sh'), { stdio: 'inherit' }); } catch (e) { /* */ }
+  } else {
+    console.log('\nStart it anytime:  npm start   (foreground)   ·   ./install-service.sh   (service)');
+  }
+  rl.close();
+})().catch((e) => { console.error('setup error:', e.message); rl.close(); process.exit(1); });

package/systemd/claude-gateway.service

@@ -0,0 +1,23 @@
+# Linux (systemd --user) unit for the Claude Code Telegram gateway.
+# Install:
+#   mkdir -p ~/.config/systemd/user
+#   sed "s#__DIR__#$(pwd)#; s#__NODE__#$(command -v node)#" systemd/claude-gateway.service \
+#     > ~/.config/systemd/user/claude-gateway.service
+#   systemctl --user daemon-reload
+#   systemctl --user enable --now claude-gateway
+#   loginctl enable-linger "$USER"     # keep it running after you log out
+# Logs:   journalctl --user -u claude-gateway -f
+[Unit]
+Description=Claude Code Telegram gateway
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=__DIR__
+ExecStart=__NODE__ __DIR__/gateway.js
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=default.target

package/test/MANUAL-TESTS.md

@@ -0,0 +1,85 @@
+# Manual verification runbook
+
+Unit tests (`npm test`) cover the pure logic. These steps cover what they can't: the real Telegram
+API and the interaction between headless injection and the live desk TUI. Do them once before
+trusting the gateway in daily use.
+
+---
+
+## Test A — Injection vs. an open TUI (the critical one, gap #1)
+
+**Why:** phone→desk injection runs `claude -p --resume <id>` when the transcript looks idle. If the
+native TUI is holding that session, we need to know whether that injection is safe (clean append),
+locks/errors, or forks the transcript.
+
+1. **Terminal 1 (the "desk"):**
+   ```bash
+   cd <your mapped repo, e.g. ~/Documents>
+   claude
+   ```
+   Send one message, e.g. `Remember the codeword: BANANA.` Wait for the reply, then **leave the TUI
+   open and idle** (don't quit).
+
+2. **Terminal 2 (the "phone", simulated):**
+   ```bash
+   cd ~/telegram_gateway
+   ./test/inject-probe.sh
+   ```
+   It auto-picks the most recent session (your Terminal-1 one) and injects a headless turn.
+
+3. **Read the probe output:**
+   - `exit_ok: true` and `result: "INJECTED_OK"` → headless resume succeeded even with the TUI open.
+   - `same_session_id` equals the session id → no new session was minted.
+   - `appended to the SAME file: yes` and `New sibling session files: 0` → **clean append, no fork.** ✅
+   - Any `non-JSON output (possible lock/conflict)`, a new sibling file, or a changed session id →
+     **injection conflicts with the open TUI.** ❗ In that case we should tighten the idle-gate to
+     also refuse injection whenever the session is the *most recently active* one (assume TUI owns it),
+     or require the desk session be closed. Tell me the result and I'll adjust.
+
+4. **Back in Terminal 1:** send another message (e.g. `What was the codeword?`). Confirm the TUI still
+   responds coherently and didn't break. Note whether it "sees" the injected turn (it generally
+   won't until you `cr`/reload — that's expected).
+
+5. **Cleanup:** quit the TUI. Run `cr` (or `claude -c`) in the repo and confirm the session loads with
+   both the desk turns and the injected `INJECTED_OK` turn present.
+
+---
+
+## Test B — Telegram permissions & topic lifecycle (gap #2)
+
+**Why:** auto-topics need the bot to be an admin with **Manage Topics**. This verifies it for real and
+leaves no junk behind (it deletes its own self-test topic).
+
+```bash
+cd ~/telegram_gateway
+node test/check-telegram.js
+```
+Expect `✅ All checks passed`. If it reports "not an admin" or "can_manage_topics: false", fix the
+bot's rights in the group (Admin → Manage Topics) and re-run.
+
+---
+
+## Test C — End-to-end mirror + auto-initiate
+
+1. Start the gateway (`npm start`, or `./install-service.sh` then `tail -f gateway.log`).
+2. In the desk TUI, open/continue a session in the mapped repo and send a message.
+3. Within ~30 min of activity (default `ACTIVE_WINDOW_MIN`) a **new topic** should appear in the
+   supergroup with an opener, and within ~2s (`POLL_MS`) your exchange should mirror in as
+   `🖥️ desk:` / assistant text / `🔧 tool` lines.
+4. From the phone, reply in that topic while the desk session is **idle** → the turn runs and streams
+   back once (no duplicate from the mirror).
+5. From the phone, `/new draft a haiku` → a brand-new topic + independent session appears.
+6. **Prune:** temporarily set `PRUNE_AFTER_DAYS` very low (e.g. via a quick config edit + restart) and
+   confirm an idle session's topic gets closed; revive the session and confirm it reopens.
+
+---
+
+## Quick reference
+
+| Check | Command |
+|---|---|
+| Unit tests | `npm test` |
+| Telegram perms | `node test/check-telegram.js` |
+| Injection safety | `./test/inject-probe.sh [session-uuid]` |
+| Live logs (service) | `tail -f gateway.log` |
+| Service state | `launchctl print gui/$(id -u)/com.claude.telegram-gateway \| grep -i state` |

package/test/check-telegram.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+'use strict';
+// Live check that the bot can do what the gateway needs: identify itself, create a forum topic,
+// post into it, and delete it. Verifies the "admin + Manage Topics" requirement without guessing.
+// Run:  node test/check-telegram.js
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+
+const cfg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'config.json'), 'utf8'));
+const { BOT_TOKEN, REPO_MAPPINGS } = cfg;
+
+function tg(method, payload) {
+  return new Promise((resolve, reject) => {
+    const data = JSON.stringify(payload || {});
+    const req = https.request({
+      hostname: 'api.telegram.org', port: 443, path: `/bot${BOT_TOKEN}/${method}`, method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data) },
+    }, (res) => { let b = ''; res.on('data', (c) => (b += c)); res.on('end', () => { try { resolve(JSON.parse(b)); } catch (e) { reject(e); } }); });
+    req.on('error', reject); req.write(data); req.end();
+  });
+}
+
+(async () => {
+  const me = await tg('getMe');
+  if (!me.ok) { console.error('❌ getMe failed — check BOT_TOKEN.', me); process.exit(1); }
+  console.log(`✅ Bot: @${me.result.username} (id ${me.result.id})`);
+
+  let allGood = true;
+  for (const chatId of Object.keys(REPO_MAPPINGS)) {
+    process.stdout.write(`\n— chat ${chatId} (${REPO_MAPPINGS[chatId]})\n`);
+
+    const chat = await tg('getChat', { chat_id: chatId });
+    if (!chat.ok) { console.error(`  ❌ getChat failed: ${chat.description}`); allGood = false; continue; }
+    console.log(`  chat type: ${chat.result.type}, forum: ${chat.result.is_forum === true}`);
+    if (!chat.result.is_forum) { console.error('  ❌ Topics/Forum not enabled on this group.'); allGood = false; }
+
+    const admin = await tg('getChatMember', { chat_id: chatId, user_id: me.result.id });
+    const status = admin.ok ? admin.result.status : 'unknown';
+    const canManage = admin.ok && (admin.result.can_manage_topics === true || status === 'creator');
+    console.log(`  bot status: ${status}, can_manage_topics: ${admin.ok ? admin.result.can_manage_topics : '?'}`);
+    if (status !== 'administrator' && status !== 'creator') { console.error('  ❌ Bot is not an admin.'); allGood = false; continue; }
+
+    const created = await tg('createForumTopic', { chat_id: chatId, name: '🔧 gateway self-test' });
+    if (!created.ok) { console.error(`  ❌ createForumTopic failed: ${created.description}`); allGood = false; continue; }
+    const threadId = created.result.message_thread_id;
+    console.log(`  ✅ created topic ${threadId}`);
+    await tg('sendMessage', { chat_id: chatId, message_thread_id: threadId, text: 'Self-test OK — deleting this topic.' });
+    const del = await tg('deleteForumTopic', { chat_id: chatId, message_thread_id: threadId });
+    console.log(del.ok ? '  ✅ posted + deleted self-test topic (cleanup done)' : `  ⚠️ could not delete self-test topic: ${del.description}`);
+  }
+
+  console.log(`\n${allGood ? '✅ All checks passed — auto-topics + mirroring will work.' : '❌ Some checks failed — fix the above before relying on auto-topics.'}`);
+  process.exit(allGood ? 0 : 1);
+})().catch((e) => { console.error('check-telegram error:', e); process.exit(1); });