@alexnodeland/claude-telegram 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-03-22
+
+### Added
+
+- **Orchestrator mode** — standalone process that spawns and manages Claude CLI subprocesses
+- **Channel mode** — MCP channel plugin that attaches Telegram to a running Claude Code session
+- **Real-time streaming** — tool calls, text, and errors stream as they happen with live status bar
+- **Session management** — create, resume, list, and stop sessions across multiple projects
+- **Navigable directory browser** — drill into folders, bookmark shortcuts, pick project roots
+- **Permission relay** — approve/deny/always prompts forwarded to Telegram with granular options
+- **Slash command pass-through** — `/cc commit`, `/cc review-pr`, etc.
+- **Mode switching** — normal, plan, and auto-accept permission modes
+- **Model switching** — sonnet, opus, haiku via `/model`
+- **Pairing-code access control** — 6-character codes, 10-minute expiry, persistent allowlist
+- **Cost tracking** — per-session token usage and cost display
+- **HTML formatting** — all output uses Telegram HTML parse mode for reliable rendering
+- **Zero Telegram SDK** — all API calls use native `fetch`
+
+[0.1.0]: https://github.com/alexnodeland/claude-telegram/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Nodeland
+
+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,191 @@
+<div align="center">
+
+# claude-telegram
+
+**Control Claude Code from Telegram — run tasks, review diffs, and ship code from your phone.**
+
+[![GitHub Release](https://img.shields.io/github/v/release/alexnodeland/claude-telegram?style=flat&color=cc785c)](https://github.com/alexnodeland/claude-telegram/releases)
+[![CI](https://img.shields.io/github/actions/workflow/status/alexnodeland/claude-telegram/ci.yml?branch=main&label=CI)](https://github.com/alexnodeland/claude-telegram/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Runtime: Bun](https://img.shields.io/badge/Bun_%3E%3D1.1-f9f1e1?logo=bun&logoColor=000)](https://bun.sh)
+[![Claude Code](https://img.shields.io/badge/Claude_Code-%3E%3D2.1-cc785c?logo=anthropic)](https://docs.anthropic.com/en/docs/claude-code)
+[![MCP](https://img.shields.io/badge/MCP-Channel_Plugin-blue)](https://modelcontextprotocol.io)
+
+<br />
+
+<img src="docs/images/working.jpg" width="340" alt="Real-time streaming in Telegram" />
+
+<br />
+
+_Tool calls stream in real time with a live status bar and cost tracking._
+
+</div>
+
+<br />
+
+A local bridge between Telegram and [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Send a message from your phone, Claude reads your codebase, edits files, runs commands, and replies — everything stays on your machine.
+
+```mermaid
+---
+config:
+  layout: elk
+---
+graph LR
+  A["You\n(Telegram)"] -->|message| B["claude-telegram\n(runs locally)"]
+  B -->|polls & streams| A
+  B -->|spawns subprocess| C["Claude Code\n(your machine)"]
+  C -->|NDJSON stream| B
+
+  style A fill:#26A5E4,color:#fff,stroke:none
+  style B fill:#1a1a2e,color:#fff,stroke:#444
+  style C fill:#cc785c,color:#fff,stroke:none
+```
+
+## Why
+
+You're away from your desk but need to:
+
+- Fix a broken CI pipeline before standup
+- Ask a question about a codebase you don't have open
+- Kick off a refactor and watch it happen
+- Review and commit code on the go
+
+Claude Telegram gives you full Claude Code access from any Telegram client — phone, tablet, desktop. No SSH, no cloud relay, no exposed ports. It runs on your machine and talks to Telegram's Bot API.
+
+## Quick start
+
+**1. Create a Telegram bot** — message [@BotFather](https://t.me/BotFather), send `/newbot`, copy the token.
+
+**2. Install and run:**
+
+```bash
+git clone https://github.com/alexnodeland/claude-telegram.git
+cd claude-telegram
+bun install
+export TELEGRAM_BOT_TOKEN=your_token_here
+bun run start:orchestrator
+```
+
+**3. Pair your Telegram account** — send `/start` to your bot, then enter the pairing code shown in your terminal.
+
+> [!TIP]
+> The **orchestrator mode** above is standalone and manages its own Claude sessions. There's also a [channel mode](docs/channel-mode.md) that attaches Telegram to an existing Claude Code session as an MCP plugin.
+
+## Features
+
+### Session management
+Start sessions in any project directory with a navigable file browser. Resume previous sessions by title. Run multiple sessions across different projects.
+
+### Real-time streaming
+Tool calls, text output, and errors stream as separate messages with a live status bar showing the current step, tool count, and running cost.
+
+### Permission control
+Permission prompts are forwarded to Telegram with granular options — approve once, for the session, or always for the project. Switch between normal, plan, and auto-accept modes.
+
+### Slash command pass-through
+Run Claude Code commands directly: `/cc commit`, `/cc review-pr 123`, `/cc diff`. Or tap through an interactive menu.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/new` | Start a session — shows a directory browser to pick your project |
+| `/resume` | Resume a previous session by title |
+| `/sessions` | List all sessions with tap-to-resume buttons |
+| `/cc` | Claude Code slash commands — menu or `/cc commit` directly |
+| `/mode` | Switch between normal / plan / auto-accept |
+| `/model` | Switch between sonnet / opus / haiku |
+| `/stop` | Stop current task or end session |
+| `/dirs` | Browse bookmarked and recent directories |
+| `/bookmark` | Save a directory shortcut: `/bookmark /path --name alias` |
+| `/cost` | Show session cost |
+| `/status` | Full session info |
+| `/help` | Show all commands |
+
+Anything that isn't a command is sent as a prompt to Claude.
+
+## Screenshots
+
+<table>
+<tr>
+<td width="50%">
+
+**Permission prompts** — approve once, for the session, or always for the project.
+
+</td>
+<td width="50%">
+
+**Directory browser** — navigate folders, bookmark shortcuts, tap to start.
+
+</td>
+</tr>
+<tr>
+<td>
+
+<img src="docs/images/permissions.jpg" width="300" alt="Permission prompt with granular options" />
+
+</td>
+<td>
+
+<img src="docs/images/new.jpg" width="300" alt="Navigable directory browser" />
+
+</td>
+</tr>
+<tr>
+<td>
+
+**`/cc` command menu** — run slash commands and switch modes from the chat.
+
+</td>
+<td>
+
+**Session list** — auto-generated titles, tap to resume.
+
+</td>
+</tr>
+<tr>
+<td>
+
+<img src="docs/images/cc.jpg" width="300" alt="/cc command menu and mode switching" />
+
+</td>
+<td>
+
+<img src="docs/images/sessions.jpg" width="300" alt="Session list with titles and resume buttons" />
+
+</td>
+</tr>
+</table>
+
+## Security
+
+- **Runs locally** — no cloud relay, no data leaves your machine, no inbound ports
+- **Pairing codes** — 6-character, 10-minute expiry, one-time use
+- **Allowlist** — only paired Telegram users can interact
+- **Permission relay** — HTTP server binds to `127.0.0.1` only
+- **Zero Telegram SDK** — native `fetch` only, minimal attack surface
+
+## Documentation
+
+| Doc | Contents |
+|---|---|
+| [Orchestrator Mode](docs/orchestrator-mode.md) | Setup, commands, permissions, streaming, sessions, env vars |
+| [Channel Mode](docs/channel-mode.md) | MCP channel plugin setup, pairing, access commands, tools |
+| [Architecture](docs/architecture.md) | System design, module map, security model, data flow |
+| [Changelog](CHANGELOG.md) | Release history |
+
+## Development
+
+```bash
+just setup             # Install deps + configure git hooks
+just dev-orchestrator  # Watch mode
+just ci                # Typecheck + lint + test (112 tests)
+just fix               # Auto-fix lint/format
+just release 1.1.0    # Tag a release
+```
+
+See [CLAUDE.md](CLAUDE.md) for architecture details and contributor guidelines.
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@alexnodeland/claude-telegram",
+  "version": "0.1.0",
+  "description": "Claude Code Channel plugin + standalone orchestrator bridging Telegram to Claude Code sessions",
+  "module": "src/index.ts",
+  "main": "src/index.ts",
+  "type": "module",
+  "bin": {
+    "claude-telegram": "./src/index.ts",
+    "claude-telegram-orchestrator": "./src/orchestrator.ts"
+  },
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "start:orchestrator": "bun run src/orchestrator.ts",
+    "dev": "bun --watch run src/index.ts",
+    "dev:orchestrator": "bun --watch run src/orchestrator.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint src/",
+    "format": "biome format --write src/",
+    "format:check": "biome format src/",
+    "check": "biome check src/",
+    "check:fix": "biome check --write src/",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "prepare": "git config core.hooksPath .githooks"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.8",
+    "@types/bun": "latest",
+    "bun-types": "^1.3.11",
+    "typescript": "^5.4.0"
+  },
+  "files": [
+    "src/",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "telegram",
+    "telegram-bot",
+    "channel",
+    "orchestrator",
+    "ai-agent",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexnodeland/claude-telegram.git"
+  },
+  "homepage": "https://github.com/alexnodeland/claude-telegram#readme",
+  "bugs": {
+    "url": "https://github.com/alexnodeland/claude-telegram/issues"
+  }
+}

package/src/access.ts

@@ -0,0 +1,73 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { PAIRING_CODE_LENGTH } from "./config.js";
+import type { AccessState, PendingPairing } from "./types.js";
+
+// ─── Persistence ──────────────────────────────────────────────────────────────
+
+export async function loadAccessState(allowlistPath: string): Promise<AccessState> {
+  try {
+    const raw = JSON.parse(await readFile(allowlistPath, "utf8")) as {
+      policy: AccessState["policy"];
+      allowlist: number[];
+    };
+    return { policy: raw.policy ?? "pairing", allowlist: raw.allowlist ?? [], pendingCodes: new Map() };
+  } catch {
+    return { policy: "pairing", allowlist: [], pendingCodes: new Map() };
+  }
+}
+
+export async function saveAccessState(allowlistPath: string, state: AccessState): Promise<void> {
+  await mkdir(dirname(allowlistPath), { recursive: true });
+  await writeFile(allowlistPath, JSON.stringify({ policy: state.policy, allowlist: state.allowlist }, null, 2));
+}
+
+// ─── Pairing Codes ────────────────────────────────────────────────────────────
+
+const CHARSET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+
+export function generatePairingCode(): string {
+  const buf = new Uint8Array(PAIRING_CODE_LENGTH);
+  crypto.getRandomValues(buf);
+  return [...buf].map((b) => CHARSET[b % CHARSET.length]).join("");
+}
+
+export function issuePairingCode(
+  state: AccessState,
+  pairing: { userId: number; chatId: number; username?: string; firstName: string },
+  ttlMs: number,
+): string {
+  const now = Date.now();
+  for (const [k, v] of state.pendingCodes) {
+    if (v.expiresAt < now) state.pendingCodes.delete(k);
+  }
+  const code = generatePairingCode();
+  state.pendingCodes.set(code, { ...pairing, expiresAt: now + ttlMs });
+  return code;
+}
+
+export function consumePairingCode(state: AccessState, code: string): PendingPairing | null {
+  const key = code.toUpperCase().trim();
+  const entry = state.pendingCodes.get(key);
+  if (!entry || entry.expiresAt < Date.now()) {
+    state.pendingCodes.delete(key);
+    return null;
+  }
+  state.pendingCodes.delete(key);
+  return entry;
+}
+
+// ─── Gate ─────────────────────────────────────────────────────────────────────
+
+export function isAllowed(state: AccessState, userId: number): boolean {
+  if (state.policy === "open") return true;
+  return state.allowlist.includes(userId);
+}
+
+export function addToAllowlist(state: AccessState, userId: number): void {
+  if (!state.allowlist.includes(userId)) state.allowlist.push(userId);
+}
+
+export function removeFromAllowlist(state: AccessState, userId: number): void {
+  state.allowlist = state.allowlist.filter((id) => id !== userId);
+}

package/src/commands.ts

@@ -0,0 +1,161 @@
+/**
+ * Parse Telegram message text into a structured command.
+ */
+
+import type { PermissionMode } from "./types.js";
+
+/** Known bot commands — used to distinguish unknown /commands from prompts. */
+const KNOWN_COMMANDS = new Set([
+  "new",
+  "resume",
+  "sessions",
+  "list",
+  "stop",
+  "end",
+  "compact",
+  "model",
+  "mode",
+  "cost",
+  "status",
+  "help",
+  "approve",
+  "cc",
+  "start",
+  "pair",
+  "dirs",
+  "bookmark",
+]);
+
+export type Command =
+  // Session management
+  | { type: "new"; cwd?: string; name?: string }
+  | { type: "resume"; target?: string }
+  | { type: "sessions" }
+  | { type: "stop" }
+  // Claude control
+  | { type: "compact" }
+  | { type: "model"; model?: string }
+  | { type: "mode"; mode?: PermissionMode }
+  | { type: "cost" }
+  | { type: "status" }
+  // Claude Code slash command pass-through
+  | { type: "cc"; slashCommand: string; args: string }
+  | { type: "cc_menu" } // /cc alone — show command picker
+  // Directory bookmarks
+  | { type: "dirs" }
+  | { type: "bookmark"; path?: string; name?: string }
+  // Admin
+  | { type: "help" }
+  | { type: "approve"; code: string }
+  // Unknown /command (not a known bot command)
+  | { type: "unknown_command"; text: string }
+  // Pass-through
+  | { type: "prompt"; text: string };
+
+export function parseCommand(text: string): Command {
+  const trimmed = text.trim();
+
+  if (trimmed === "/new" || trimmed.startsWith("/new ")) {
+    const args = trimmed.slice(4).trim();
+    if (!args) return { type: "new" };
+
+    const nameMatch = args.match(/--name\s+(\S+)/);
+    const name = nameMatch?.[1];
+    const cwd = args.replace(/--name\s+\S+/, "").trim() || undefined;
+    return { type: "new", cwd, name };
+  }
+
+  if (trimmed === "/resume" || trimmed.startsWith("/resume ")) {
+    const target = trimmed.slice(7).trim() || undefined;
+    return { type: "resume", target };
+  }
+
+  if (trimmed === "/sessions" || trimmed === "/list") {
+    return { type: "sessions" };
+  }
+
+  if (trimmed === "/stop" || trimmed === "/end") {
+    return { type: "stop" };
+  }
+
+  if (trimmed === "/compact") {
+    return { type: "compact" };
+  }
+
+  if (trimmed === "/model" || trimmed.startsWith("/model ")) {
+    const model = trimmed.slice(6).trim() || undefined;
+    return { type: "model", model };
+  }
+
+  // /mode [normal|plan|auto-accept]
+  if (trimmed === "/mode" || trimmed.startsWith("/mode ")) {
+    const modeArg = trimmed.slice(5).trim() || undefined;
+    if (!modeArg) return { type: "mode" };
+    const valid: PermissionMode[] = ["normal", "plan", "auto-accept"];
+    if (valid.includes(modeArg as PermissionMode)) {
+      return { type: "mode", mode: modeArg as PermissionMode };
+    }
+    // Shorthand aliases
+    if (modeArg === "auto") return { type: "mode", mode: "auto-accept" };
+    if (modeArg === "accept") return { type: "mode", mode: "auto-accept" };
+    return { type: "mode" }; // invalid mode → show picker
+  }
+
+  if (trimmed === "/cost") {
+    return { type: "cost" };
+  }
+
+  if (trimmed === "/status") {
+    return { type: "status" };
+  }
+
+  if (trimmed === "/help") {
+    return { type: "help" };
+  }
+
+  if (trimmed.startsWith("/approve ")) {
+    const code = trimmed.slice(9).trim();
+    if (code) return { type: "approve", code };
+  }
+
+  // /cc alone — show command picker menu
+  if (trimmed === "/cc" || trimmed === "/cc ") {
+    return { type: "cc_menu" };
+  }
+
+  // /cc <slashCommand> [args] — Claude Code slash command pass-through
+  if (trimmed.startsWith("/cc ")) {
+    const rest = trimmed.slice(4).trim();
+    if (rest) {
+      const spaceIdx = rest.indexOf(" ");
+      const slashCommand = spaceIdx === -1 ? rest : rest.slice(0, spaceIdx);
+      const args = spaceIdx === -1 ? "" : rest.slice(spaceIdx + 1).trim();
+      return { type: "cc", slashCommand, args };
+    }
+  }
+
+  // /dirs — list bookmarked directories
+  if (trimmed === "/dirs") {
+    return { type: "dirs" };
+  }
+
+  // /bookmark [path] [--name alias]
+  if (trimmed === "/bookmark" || trimmed.startsWith("/bookmark ")) {
+    const args = trimmed.slice(9).trim();
+    if (!args) return { type: "bookmark" };
+    const nameMatch = args.match(/--name\s+(\S+)/);
+    const name = nameMatch?.[1];
+    const path = args.replace(/--name\s+\S+/, "").trim() || undefined;
+    return { type: "bookmark", path, name };
+  }
+
+  // Detect unknown /commands (single-word slash that isn't a known command)
+  if (trimmed.startsWith("/")) {
+    const match = trimmed.match(/^\/(\S+)/);
+    if (match?.[1] && !KNOWN_COMMANDS.has(match[1].toLowerCase())) {
+      return { type: "unknown_command", text: trimmed };
+    }
+  }
+
+  return { type: "prompt", text: trimmed };
+}

package/src/config.ts

@@ -0,0 +1,40 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Config } from "./types.js";
+
+const HOME = process.env.HOME ?? "/tmp";
+const DATA_DIR = join(HOME, ".claude", "channels", "telegram");
+
+function readEnvFile(path: string): Record<string, string> {
+  try {
+    const lines = readFileSync(path, "utf8").split("\n");
+    const result: Record<string, string> = {};
+    for (const line of lines) {
+      const match = line.match(/^([A-Z_]+)=(.+)$/);
+      if (match?.[1] && match[2]) result[match[1]] = match[2].trim();
+    }
+    return result;
+  } catch {
+    return {};
+  }
+}
+
+export function loadConfig(): Config {
+  const envFile = readEnvFile(join(DATA_DIR, ".env"));
+
+  const botToken = process.env.TELEGRAM_BOT_TOKEN ?? envFile.TELEGRAM_BOT_TOKEN ?? "";
+
+  return {
+    botToken,
+    dataDir: DATA_DIR,
+    allowlistPath: join(DATA_DIR, "allowlist.json"),
+    pollIntervalMs: 1_500,
+    pairingCodeTtlMs: 10 * 60 * 1_000, // 10 minutes
+    maxFileSizeBytes: 50 * 1024 * 1024, // 50 MB
+  };
+}
+
+export const TELEGRAM_API_BASE = "https://api.telegram.org";
+export const PAIRING_CODE_LENGTH = 6;
+export const TYPING_INTERVAL_MS = 4_500;
+export const RELAY_PROMPT_TIMEOUT_MS = 120_000; // 2 minutes

package/src/html.ts

@@ -0,0 +1,25 @@
+/**
+ * HTML escape and formatting utilities for Telegram's HTML parse mode.
+ *
+ * Telegram HTML supports: <b>, <i>, <code>, <pre>, <a>, <s>, <u>, <tg-spoiler>.
+ * Only three characters require escaping: & < >
+ */
+
+/** Escape text for safe inclusion in Telegram HTML messages. */
+export function escapeHtml(text: string): string {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** Formatting helpers — each auto-escapes content. */
+export const fmt = {
+  bold: (text: string) => `<b>${escapeHtml(text)}</b>`,
+  italic: (text: string) => `<i>${escapeHtml(text)}</i>`,
+  code: (text: string) => `<code>${escapeHtml(text)}</code>`,
+  pre: (text: string) => `<pre>${escapeHtml(text)}</pre>`,
+  preBlock: (text: string, language?: string) =>
+    language
+      ? `<pre><code class="language-${escapeHtml(language)}">${escapeHtml(text)}</code></pre>`
+      : `<pre>${escapeHtml(text)}</pre>`,
+  link: (text: string, url: string) => `<a href="${escapeHtml(url)}">${escapeHtml(text)}</a>`,
+  strikethrough: (text: string) => `<s>${escapeHtml(text)}</s>`,
+};