claude-telegram 0.1.0

package/README.md

@@ -0,0 +1,283 @@
+# claude-telegram
+
+A simple and modular Telegram orchestrator on top of Claude Code CLI.
+
+One npm package that connects a Telegram bot to Claude Code via `--resume` sessions, with whitelist access control and live activity status.
+
+## claude-telegram vs OpenClaw
+
+| | claude-telegram | [OpenClaw](https://github.com/openclaw/openclaw) |
+|---|---|---|
+| Core | ~1500 LOC, one dependency (grammY) | 50+ integrations, large codebase |
+| Approach | Minimal orchestrator — Claude Code does the work | Full-featured AI assistant platform |
+| Extensibility | Module system — add anything you need | Built-in, growing feature set |
+| Control | You own the code, easy to audit and modify | Community-driven, fast-moving |
+| Setup | `npx claude-telegram start` | Multi-step setup |
+
+> Both are valid choices. claude-telegram is for those who prefer a small, predictable core that they extend themselves.
+
+## Installation
+
+**1. Get a server** — a VPS, a home PC, anything with internet access.
+
+**2. Install Claude Code:**
+```bash
+curl -fsSL https://claude.ai/install.sh | bash
+```
+
+**3. Give Claude the link and ask it to install:**
+```bash
+claude "install claude-telegram from github.com/bluzir/claude-telegram and set it up for my Telegram bot"
+```
+
+## Quick Start
+
+```bash
+mkdir my-agent && cd my-agent
+echo "You are a helpful assistant." > CLAUDE.md
+
+cat > claude-telegram.yaml << 'EOF'
+token: ${MY_BOT_TOKEN}
+workspace: .
+whitelist: [YOUR_USER_ID]
+permission_mode: acceptEdits
+EOF
+
+export MY_BOT_TOKEN="123456:ABC-DEF..."
+npx claude-telegram start
+```
+
+Don't know your Telegram user ID? Run `npx claude-telegram whoami` and send a message to the bot.
+
+## Config
+
+Create `claude-telegram.yaml` in your project root:
+
+```yaml
+token: ${TELEGRAM_BOT_TOKEN}        # env var interpolation
+workspace: /path/to/workspace        # cwd for Claude CLI
+
+# Who can use the bot (Telegram user IDs)
+# Empty list = NO ONE (secure by default)
+whitelist:
+  - 16643982
+
+# What Claude can do
+# default | acceptEdits | bypassPermissions
+permission_mode: acceptEdits
+
+# --- Optional ---
+# claude_path: /usr/local/bin/claude   # default: "claude" from PATH
+# timeout: 300                          # seconds, default: 300
+# model: sonnet                         # model override
+# system_prompt: "Reply in Russian"     # injected into every call
+# add_dirs:                             # additional dirs for Claude
+#   - /path/to/shared/data
+
+# modules:                              # optional plugin modules (loaded at startup)
+#   - import: ./modules/voice.mjs       # resolved relative to `workspace`
+#     options:
+#       provider: openai
+#   - import: claude-telegram-whoop-module
+#     options:
+#       client_id: ${WHOOP_CLIENT_ID}
+```
+
+Environment variables are interpolated with `${VAR_NAME}` syntax.
+
+## Workspace
+
+The `workspace` field in config is just the working directory (`cwd`) for Claude CLI. It can be any directory — claude-telegram doesn't care what's inside. Claude Code will use whatever `CLAUDE.md`, `.claude/agents/`, `.claude/skills/`, and other project files it finds there, exactly as it would in the terminal.
+
+### Simple setup
+
+The simplest workspace is a directory with just a `CLAUDE.md`:
+
+```
+my-agent/
+├── CLAUDE.md                    # Instructions for Claude
+├── claude-telegram.yaml         # Bot config
+└── data/                        # Runtime data (auto-created)
+```
+
+### Using an existing project
+
+Any project that works with Claude Code works with claude-telegram — just point `workspace` at it:
+
+```bash
+# Clone any project that has CLAUDE.md / .claude/ setup
+git clone https://github.com/bluzir/claude-pipe
+```
+
+```yaml
+# claude-telegram.yaml
+token: ${MY_BOT_TOKEN}
+workspace: ./claude-pipe/examples/research-pipeline
+whitelist: [YOUR_USER_ID]
+permission_mode: acceptEdits
+```
+
+Claude will see the project's `CLAUDE.md`, agents, skills, commands, MCP servers — everything. You don't need to copy or restructure anything.
+
+### Multi-agent setup
+
+Run multiple bots, each pointing to its own project:
+
+```yaml
+# researcher.yaml
+token: ${RESEARCHER_BOT_TOKEN}
+workspace: ./research-pipeline
+whitelist: [YOUR_USER_ID]
+permission_mode: acceptEdits
+timeout: 600
+system_prompt: "You are a research agent. Be thorough and cite sources."
+add_dirs:
+  - ./shared
+```
+
+```yaml
+# assistant.yaml
+token: ${ASSISTANT_BOT_TOKEN}
+workspace: ./assistant
+whitelist: [YOUR_USER_ID]
+permission_mode: acceptEdits
+```
+
+```bash
+npx claude-telegram start --config researcher.yaml
+npx claude-telegram start --config assistant.yaml
+```
+
+Each bot gets its own workspace, sessions, and Telegram token. They share nothing unless you explicitly use `add_dirs`.
+
+## Modules
+
+You can extend the bot without bloating the core by adding optional modules that register extra handlers (voice/video, API integrations, etc.).
+
+Module import rules:
+- Relative paths are resolved against `workspace`
+- Anything else is treated as a package specifier and resolved by Node
+- Modules must export a default object or a default factory function
+
+Minimal module example (`{workspace}/modules/hello.mjs`):
+
+```js
+export default function createModule() {
+  return {
+    name: "hello",
+    commands: [{ command: "/hi", description: "Say hi" }],
+    register({ bot, dispatchToClaude }) {
+      bot.command("hi", async (ctx) => {
+        await dispatchToClaude(ctx, "Say hi in one sentence.");
+      });
+    },
+  };
+}
+```
+
+### Hooks (memory, security, post-processing)
+
+Modules can also hook into the request pipeline:
+
+- `beforeClaude(ctx, message)` — deny or transform the user's message before it is sent to Claude
+- `afterClaude(ctx, result)` — observe/transform Claude result before it is sent back to Telegram
+
+Security example (deny messages containing a secret keyword):
+
+```js
+export default function createModule() {
+  return {
+    name: "security",
+    async beforeClaude(ctx, message) {
+      if (message.includes("OPENAI_API_KEY")) {
+        return { action: "deny", reply: "Denied: looks like a secret." };
+      }
+      return { action: "continue" };
+    },
+  };
+}
+```
+
+Memory-ish example (prepend extra context):
+
+```js
+export default function createModule() {
+  return {
+    name: "memory",
+    async beforeClaude(ctx, message) {
+      const extraContext = "Context: you are talking to the same user as before.";
+      return { action: "continue", message: `${extraContext}\n\n${message}` };
+    },
+    async afterClaude(ctx, result) {
+      // Store result.output somewhere if you want (file/db/vector store).
+      return result;
+    },
+  };
+}
+```
+
+## CLI
+
+```bash
+npx claude-telegram start                    # uses claude-telegram.yaml in CWD
+npx claude-telegram start --config ./my.yaml # custom config path
+npx claude-telegram check                    # validate config + claude CLI
+npx claude-telegram whoami                   # get your Telegram user ID
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/start` | Welcome message |
+| `/cancel` | Stop current request |
+| `/clear` | Reset conversation (new session) |
+| `/help` | Show available commands |
+
+## How It Works
+
+- Each user gets a persistent Claude session via `--resume <sessionId>`
+- Sessions survive bot restarts (stored in `~/.claude/` by Claude CLI)
+- Session mapping stored in `{workspace}/data/.claude-telegram/sessions.json`
+- Bot responds in private chats only (ignores group/supergroup/channel)
+- One message at a time per user (concurrent messages get "Still working..." reply)
+- Live activity status shows what Claude is doing (reading, editing, searching, etc.)
+- Messages are split at 3800 chars and formatted as Telegram MarkdownV2
+
+## Programmatic API
+
+```typescript
+import { createBot, loadConfig } from "claude-telegram";
+
+// From config file
+const config = loadConfig("./claude-telegram.yaml");
+
+// Or build config directly
+const bot = createBot({
+  token: process.env.BOT_TOKEN!,
+  workspace: "/path/to/workspace",
+  whitelist: [16643982],
+  permissionMode: "acceptEdits",
+  claudePath: "claude",
+  timeout: 300,
+});
+
+await bot.start();
+```
+
+## What's NOT Included
+
+This is intentionally minimal. Not included:
+
+- Voice/photo messages
+- Multi-bot routing or gateway
+- Approval system (use Claude CLI's `--permission-mode`)
+- Budget tracking
+- Web dashboard
+- Queue system (one message at a time, extras are rejected)
+
+Any of these can be added as a [module](#modules) without touching the core.
+
+## License
+
+MIT

package/dist/bin/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/bin/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../bin/cli.ts"],"names":[],"mappings":""}

package/dist/bin/cli.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { loadConfig } from "../src/config.js";
+import { startBot } from "../src/bot.js";
+import { Bot } from "grammy";
+const args = process.argv.slice(2);
+const command = args[0];
+function getConfigPath() {
+    const configIdx = args.indexOf("--config");
+    if (configIdx !== -1 && args[configIdx + 1]) {
+        return args[configIdx + 1];
+    }
+    return undefined;
+}
+async function cmdStart() {
+    const config = loadConfig(getConfigPath());
+    await startBot(config);
+}
+function cmdCheck() {
+    console.log("[check] Validating config...");
+    let config;
+    try {
+        config = loadConfig(getConfigPath());
+        console.log(`  ✓ Config loaded`);
+        console.log(`  ✓ Workspace: ${config.workspace}`);
+        console.log(`  ✓ Whitelist: ${config.whitelist.length} user(s)`);
+        console.log(`  ✓ Permission mode: ${config.permissionMode}`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`  ✗ Config error: ${msg}`);
+        process.exit(1);
+    }
+    // Check Claude CLI
+    try {
+        const version = execFileSync(config.claudePath, ["--version"], {
+            encoding: "utf-8",
+        }).trim();
+        console.log(`  ✓ Claude CLI: ${version}`);
+    }
+    catch {
+        console.error(`  ✗ Claude CLI not found or not executable: ${config.claudePath}`);
+        process.exit(1);
+    }
+    // Sanity-check required flags used by this package (no API calls).
+    try {
+        const help = execFileSync(config.claudePath, ["--help"], {
+            encoding: "utf-8",
+        });
+        const required = [
+            "--output-format",
+            "stream-json",
+            "--permission-mode",
+            "--resume",
+            "--session-id",
+        ];
+        const missing = required.filter((s) => !help.includes(s));
+        if (missing.length > 0) {
+            console.error(`  ✗ Claude CLI is missing required flags: ${missing.join(", ")}`);
+            process.exit(1);
+        }
+        console.log("  ✓ Claude CLI flags look compatible");
+    }
+    catch {
+        console.error("  ✗ Failed to validate Claude CLI help output");
+        process.exit(1);
+    }
+    console.log("\nAll checks passed.");
+}
+async function cmdWhoami() {
+    // Determine token: from --config or env
+    let token;
+    try {
+        const config = loadConfig(getConfigPath());
+        token = config.token;
+    }
+    catch {
+        // If no config, try env directly
+        token = process.env.TELEGRAM_BOT_TOKEN;
+    }
+    if (!token) {
+        console.error("No bot token found. Provide a config file or set TELEGRAM_BOT_TOKEN.");
+        process.exit(1);
+    }
+    const bot = new Bot(token);
+    bot.on("message", async (ctx) => {
+        if (ctx.chat?.type !== "private") {
+            try {
+                await ctx.reply("Please message me in a private chat.");
+            }
+            catch {
+                // Ignore
+            }
+            return;
+        }
+        const userId = ctx.from?.id;
+        const username = ctx.from?.username || "(no username)";
+        const name = [ctx.from?.first_name, ctx.from?.last_name].filter(Boolean).join(" ") ||
+            "(no name)";
+        await ctx.reply(`Your Telegram info:\n\n` +
+            `User ID: ${userId}\n` +
+            `Username: @${username}\n` +
+            `Name: ${name}\n\n` +
+            `Add ${userId} to your whitelist config.`);
+    });
+    console.log("[whoami] Bot started. Send any message to get your user ID.");
+    console.log("[whoami] Press Ctrl+C to stop.\n");
+    await bot.start();
+}
+// --- Main ---
+switch (command) {
+    case "start":
+        cmdStart().catch((err) => {
+            console.error("Fatal:", err instanceof Error ? err.message : err);
+            process.exit(1);
+        });
+        break;
+    case "check":
+        cmdCheck();
+        break;
+    case "whoami":
+        cmdWhoami().catch((err) => {
+            console.error("Fatal:", err instanceof Error ? err.message : err);
+            process.exit(1);
+        });
+        break;
+    default:
+        console.log(`claude-telegram — Telegram bot for Claude Code CLI
+
+Usage:
+  claude-telegram start [--config path]   Start the bot
+  claude-telegram check [--config path]   Validate config & dependencies
+  claude-telegram whoami                  Get your Telegram user ID
+`);
+        if (command && command !== "help" && command !== "--help") {
+            process.exit(1);
+        }
+        break;
+}
+//# sourceMappingURL=cli.js.map

package/dist/bin/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../bin/cli.ts"],"names":[],"mappings":"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"}

package/dist/src/activity.d.ts

@@ -0,0 +1,17 @@
+import type { Bot } from "grammy";
+import type { StreamJsonEvent } from "./types.js";
+interface ActivityStatusOptions {
+    api: Bot["api"];
+    chatId: number;
+    messageId: number;
+}
+/**
+ * Create an activity status updater that edits a Telegram message
+ * with current Claude activity and elapsed time.
+ */
+export declare function createActivityStatus(options: ActivityStatusOptions): {
+    onEvent: (event: StreamJsonEvent) => void;
+    stop: () => void;
+};
+export {};
+//# sourceMappingURL=activity.d.ts.map

package/dist/src/activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../../src/activity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAClC,OAAO,KAAK,EAAe,eAAe,EAAE,MAAM,YAAY,CAAC;AAsD/D,UAAU,qBAAqB;IAC7B,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB;qBA0BzC,eAAe;;EAkBxC"}

package/dist/src/activity.js

@@ -0,0 +1,91 @@
+const MIN_UPDATE_INTERVAL_MS = 3_000;
+const TOOL_LABELS = {
+    Read: "reading",
+    Edit: "editing",
+    Write: "writing",
+    Bash: "command",
+    Grep: "searching",
+    Glob: "searching",
+    WebFetch: "web",
+    WebSearch: "web",
+    Task: "subagent",
+};
+const ACTIVITY_DISPLAY = {
+    thinking: "💭 Thinking",
+    reading: "📖 Reading",
+    editing: "✏️ Editing",
+    writing: "📝 Writing",
+    searching: "🔍 Searching",
+    command: "🔧 Running command",
+    web: "🌐 Web lookup",
+    subagent: "🧩 Sub-agent",
+    mcp: "🔌 MCP tool",
+};
+function formatElapsed(ms) {
+    const totalSec = Math.floor(ms / 1000);
+    const min = Math.floor(totalSec / 60);
+    const sec = totalSec % 60;
+    return `${min}:${String(sec).padStart(2, "0")}`;
+}
+/**
+ * Detect activity from a stream-json event.
+ */
+function detectActivity(event) {
+    if (event.type === "assistant" && event.message?.content) {
+        for (const block of event.message.content) {
+            if (block.type === "tool_use" && block.name) {
+                // Check known tools
+                const key = TOOL_LABELS[block.name];
+                if (key)
+                    return key;
+                // MCP tools (mcp__*)
+                if (block.name.startsWith("mcp__"))
+                    return "mcp";
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Create an activity status updater that edits a Telegram message
+ * with current Claude activity and elapsed time.
+ */
+export function createActivityStatus(options) {
+    const { api, chatId, messageId } = options;
+    const startTime = Date.now();
+    let currentLabel = ACTIVITY_DISPLAY.thinking;
+    let lastSentText = "";
+    let stopped = false;
+    const timer = setInterval(sendUpdate, MIN_UPDATE_INTERVAL_MS);
+    async function sendUpdate() {
+        if (stopped)
+            return;
+        const elapsed = formatElapsed(Date.now() - startTime);
+        const text = `${currentLabel}  ⏱ ${elapsed}`;
+        if (text === lastSentText)
+            return;
+        try {
+            await api.editMessageText(chatId, messageId, text);
+            lastSentText = text;
+        }
+        catch {
+            // Silently ignore edit failures (rate limit, message deleted, etc.)
+        }
+    }
+    function onEvent(event) {
+        if (stopped)
+            return;
+        const key = detectActivity(event);
+        if (key) {
+            currentLabel = ACTIVITY_DISPLAY[key];
+        }
+    }
+    function stop() {
+        stopped = true;
+        clearInterval(timer);
+    }
+    // Send first update immediately
+    void sendUpdate();
+    return { onEvent, stop };
+}
+//# sourceMappingURL=activity.js.map

package/dist/src/activity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.js","sourceRoot":"","sources":["../../src/activity.ts"],"names":[],"mappings":"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"}

package/dist/src/bot.d.ts

@@ -0,0 +1,16 @@
+import { Bot } from "grammy";
+import type { BotConfig } from "./types.js";
+import { type BotModule, type ModuleContext } from "./modules.js";
+export interface CreateBotOptions {
+    modules?: BotModule[];
+    onModuleContext?: (ctx: ModuleContext) => void;
+}
+/**
+ * Create and configure a Grammy bot connected to Claude CLI.
+ */
+export declare function createBot(config: BotConfig, options?: CreateBotOptions): Bot;
+/**
+ * Start the bot with graceful shutdown handling.
+ */
+export declare function startBot(config: BotConfig): Promise<void>;
+//# sourceMappingURL=bot.d.ts.map

package/dist/src/bot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../../src/bot.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAgB,MAAM,QAAQ,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAgB,MAAM,YAAY,CAAC;AAM1D,OAAO,EAAe,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAE/E,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC;IACtB,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,CAAC;CAChD;AAsBD;;GAEG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,GAAE,gBAAqB,GAAG,GAAG,CA0WhF;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAiD/D"}