ccbot 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Claude Code Bot Contributors
+
+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.en.md

@@ -0,0 +1,158 @@
+# 🤖 ccbot — Claude Code ↔ Telegram Notification Bot
+
+[Tiếng Việt](./README.md)
+
+> Get Telegram notifications when Claude Code completes a response — with git diff, processing time, and result summary.
+
+---
+
+## Problem
+
+You're using Claude Code on your computer. You step away with your phone but have no idea if Claude Code is done yet or what files it changed.
+
+**ccbot** is a lightweight bridge between Claude Code and Telegram — when Claude Code finishes, you get a notification right on your phone.
+
+```
+Claude Code completes response
+        ↓
+  Stop Hook triggers
+        ↓
+  ccbot receives event
+        ↓
+  Telegram notification 📱
+```
+
+## Features
+
+- 🔔 **Auto notification** — Claude Code finishes → Telegram notifies you instantly
+- 📂 **Git diff included** — see changed files without opening your computer
+- ⏱ **Processing time** — know how long Claude Code took
+- 📝 **Response summary** — quick glance at what Claude Code replied
+- 🔐 **User whitelist** — only authorized users can use the bot
+- 📄 **Auto-split messages** — long responses are automatically paginated `[1/N]`
+
+## Requirements
+
+- **Node.js** ≥ 18
+- **pnpm** (or npm/yarn)
+- **Telegram Bot Token** — create from [@BotFather](https://t.me/BotFather)
+- **Telegram User ID** — get from [@userinfobot](https://t.me/userinfobot)
+
+## Getting Started
+
+### Option 1: Global install (recommended)
+
+```bash
+pnpm add -g ccbot
+ccbot setup
+```
+
+### Option 2: npx (no install needed)
+
+```bash
+npx ccbot setup
+```
+
+### Option 3: Clone repo (for development)
+
+```bash
+git clone https://github.com/palooza-kaida/ccbot.git
+cd ccbot
+pnpm install
+pnpm setup
+```
+
+The setup wizard will guide you step by step:
+
+```
+┌  🤖 ccbot setup
+│
+◇  Telegram Bot Token
+│  your-bot-token
+│
+◇  Your Telegram User ID
+│  your-user-id
+│
+◆  Config saved
+◆  Hook installed → ~/.claude/settings.json
+◆  Chat ID registered
+│
+└  🎉 Setup complete!
+```
+
+<details>
+<summary>Manual setup (without wizard)</summary>
+
+Create `~/.ccbot/config.json`:
+
+```json
+{
+  "telegram_bot_token": "123456:ABC-xxx",
+  "user_id": 123456789,
+  "hook_port": 9377
+}
+```
+
+Then run `ccbot setup` to install the hook and register your chat ID.
+
+</details>
+
+## Usage
+
+### Start the bot
+
+```bash
+# Global install
+ccbot
+
+# Or npx
+npx ccbot
+
+# Or local dev
+pnpm dev
+```
+
+Once running, use Claude Code as usual → notifications will arrive on Telegram.
+
+### Telegram Commands
+
+| Command   | Description                                         |
+|-----------|-----------------------------------------------------|
+| `/start`  | Re-register chat (auto during setup, rarely needed) |
+| `/ping`   | Check if bot is alive                               |
+| `/status` | View bot status                                     |
+
+### Sample Notification
+
+```
+🤖 Claude Code Response
+📂 my-project | ⏱ 45s
+
+Fixed authentication bug in login.go. Main changes:
+- Fix missing error check at line 42
+- Add input validation...
+
+📂 Changes:
+✏️ src/login.go
+➕ src/validator.go
+❌ src/old_auth.go
+```
+
+## Uninstall
+
+```bash
+ccbot uninstall
+```
+
+```
+┌  🗑️  Uninstalling ccbot
+│
+◆  Hook removed from ~/.claude/settings.json
+◆  Removed ~/.ccbot/ (config, state, hooks)
+│
+└  ccbot uninstalled
+```
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,158 @@
+# 🤖 ccbot — Claude Code ↔ Telegram Notification Bot
+
+[English](./README.en.md)
+
+> Nhận thông báo Telegram khi Claude Code hoàn thành response — kèm git diff, thời gian xử lý, và tóm tắt kết quả.
+
+---
+
+## Vấn đề giải quyết
+
+Bạn đang dùng Claude Code trên máy tính. Ra ngoài cầm điện thoại nhưng không biết Claude Code đã xong chưa, thay đổi file nào.
+
+**ccbot** là cầu nối nhẹ giữa Claude Code và Telegram — khi Claude Code xong việc, bạn nhận notification ngay trên điện thoại.
+
+```
+Claude Code xong response
+        ↓
+  Stop Hook trigger
+        ↓
+  ccbot nhận event
+        ↓
+  Telegram notification 📱
+```
+
+## Tính năng
+
+- 🔔 **Notification tự động** — Claude Code xong → Telegram nhận tin ngay
+- 📂 **Git diff kèm theo** — biết file nào thay đổi mà không cần mở máy tính
+- ⏱ **Thời gian xử lý** — biết Claude Code chạy bao lâu
+- 📝 **Tóm tắt response** — xem nhanh Claude Code trả lời gì
+- 🔐 **Whitelist user** — chỉ user được phép mới dùng được bot
+- 📄 **Auto-split message** — response dài tự động chia page `[1/N]`
+
+## Yêu cầu
+
+- **Node.js** ≥ 18
+- **pnpm** (hoặc npm/yarn)
+- **Telegram Bot Token** — tạo từ [@BotFather](https://t.me/BotFather)
+- **Telegram User ID** — lấy từ [@userinfobot](https://t.me/userinfobot)
+
+## Bắt đầu
+
+### Cách 1: Global install (khuyến nghị)
+
+```bash
+pnpm add -g ccbot
+ccbot setup
+```
+
+### Cách 2: npx (không cần cài)
+
+```bash
+npx ccbot setup
+```
+
+### Cách 3: Clone repo (cho development)
+
+```bash
+git clone https://github.com/palooza-kaida/ccbot.git
+cd ccbot
+pnpm install
+pnpm setup
+```
+
+Setup wizard sẽ hướng dẫn từng bước:
+
+```
+┌  🤖 ccbot setup
+│
+◇  Telegram Bot Token
+│  your-bot-token
+│
+◇  Your Telegram User ID
+│  your-user-id
+│
+◆  Config saved
+◆  Hook installed → ~/.claude/settings.json
+◆  Chat ID registered
+│
+└  🎉 Setup complete!
+```
+
+<details>
+<summary>Thiết lập thủ công (không dùng wizard)</summary>
+
+Tạo file `~/.ccbot/config.json`:
+
+```json
+{
+  "telegram_bot_token": "123456:ABC-xxx",
+  "user_id": 123456789,
+  "hook_port": 9377
+}
+```
+
+Sau đó chạy `ccbot setup` để cài hook và đăng ký chat ID.
+
+</details>
+
+## Sử dụng
+
+### Khởi động bot
+
+```bash
+# Global install
+ccbot
+
+# Hoặc npx
+npx ccbot
+
+# Hoặc local dev
+pnpm dev
+```
+
+Bot chạy xong → dùng Claude Code bình thường → notification tự đến Telegram.
+
+### Telegram Commands
+
+| Command   | Chức năng                                       |
+|-----------|---------------------------------------------------|
+| `/start`  | Đăng ký lại chat (tự động khi setup, ít khi cần) |
+| `/ping`   | Kiểm tra bot còn sống không                      |
+| `/status` | Xem trạng thái bot                               |
+
+### Notification mẫu
+
+```
+🤖 Claude Code Response
+📂 my-project | ⏱ 45s
+
+Đã sửa bug authentication trong login.go. Thay đổi chính:
+- Fix missing error check ở dòng 42
+- Thêm input validation...
+
+📂 Changes:
+✏️ src/login.go
+➕ src/validator.go
+❌ src/old_auth.go
+```
+
+## Gỡ cài đặt
+
+```bash
+ccbot uninstall
+```
+
+```
+┌  🗑️  Uninstalling ccbot
+│
+◆  Hook removed from ~/.claude/settings.json
+◆  Removed ~/.ccbot/ (config, state, hooks)
+│
+└  ccbot uninstalled
+```
+
+## License
+
+MIT

package/dist/commands/help.d.ts

@@ -0,0 +1 @@
+export declare function runHelp(): void;

package/dist/commands/help.js

@@ -0,0 +1,17 @@
+import * as p from "@clack/prompts";
+import { detectCliPrefix } from "../utils/install-detection.js";
+export function runHelp() {
+    const prefix = detectCliPrefix();
+    p.intro("🤖 ccbot — Claude Code ↔ Telegram Notification Bot");
+    p.log.message([
+        `Usage: ${prefix} [command]`,
+        "",
+        "Commands:",
+        "  (none)      Start the bot",
+        "  setup       Interactive setup (config + hooks)",
+        "  update      Update ccbot to latest version",
+        "  uninstall   Remove all ccbot data and hooks",
+        "  help        Show this help message",
+    ].join("\n"));
+    p.outro("docs → https://github.com/palooza-kaida/ccbot");
+}

package/dist/commands/setup.d.ts

@@ -0,0 +1 @@
+export declare function runSetup(): Promise<void>;

package/dist/commands/setup.js

@@ -0,0 +1,103 @@
+import * as p from "@clack/prompts";
+import { mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { ConfigManager } from "../config-manager.js";
+import { HookInstaller } from "../hook/hook-installer.js";
+import { detectCliPrefix } from "../utils/install-detection.js";
+import { formatError } from "../utils/error-utils.js";
+export async function runSetup() {
+    p.intro("🤖 ccbot setup");
+    let existing = null;
+    try {
+        existing = ConfigManager.load();
+    }
+    catch { }
+    const credentials = await promptCredentials(existing);
+    const config = buildConfig(credentials, existing);
+    saveConfig(config);
+    installHook(config);
+    registerChatId(config.user_id);
+    const startCommand = detectCliPrefix();
+    p.outro(`🎉 Setup complete!\n\n  Next steps:\n  1. Start bot:  ${startCommand}\n  2. Use Claude Code normally → notifications will arrive`);
+}
+async function promptCredentials(existing) {
+    const result = await p.group({
+        token: () => p.text({
+            message: "Telegram Bot Token",
+            placeholder: "Get from @BotFather → /newbot",
+            initialValue: existing?.telegram_bot_token ?? "",
+            validate(value) {
+                if (!value || !value.trim())
+                    return "Bot token is required";
+                if (!value.includes(":"))
+                    return "Invalid format (expected: 123456:ABC-xxx)";
+            },
+        }),
+        userId: () => p.text({
+            message: "Your Telegram User ID",
+            placeholder: "Send /start to @userinfobot",
+            initialValue: existing?.user_id?.toString() ?? "",
+            validate(value) {
+                if (!value || !value.trim())
+                    return "User ID is required";
+                if (isNaN(parseInt(value, 10)))
+                    return "Must be a number";
+            },
+        }),
+    }, {
+        onCancel: () => {
+            p.cancel("Setup cancelled.");
+            process.exit(0);
+        },
+    });
+    return {
+        token: result.token.trim(),
+        userId: parseInt(result.userId.trim(), 10),
+    };
+}
+function buildConfig(credentials, existing) {
+    return {
+        telegram_bot_token: credentials.token,
+        user_id: credentials.userId,
+        hook_port: existing?.hook_port || 9377,
+        hook_secret: existing?.hook_secret || ConfigManager.generateSecret(),
+    };
+}
+function saveConfig(config) {
+    ConfigManager.save(config);
+    p.log.success("Config saved");
+}
+function installHook(config) {
+    try {
+        HookInstaller.install(config.hook_port, config.hook_secret);
+        p.log.success("Hook installed → ~/.claude/settings.json");
+    }
+    catch (err) {
+        const msg = formatError(err);
+        if (msg.includes("already installed")) {
+            p.log.step("Hook already installed");
+        }
+        else {
+            p.log.error(`Hook installation failed: ${msg}`);
+            throw new Error(`install hook: ${msg}`);
+        }
+    }
+}
+function registerChatId(userId) {
+    const stateDir = join(homedir(), ".ccbot");
+    const stateFile = join(stateDir, "state.json");
+    let state = { chat_id: null };
+    try {
+        const data = readFileSync(stateFile, "utf-8");
+        state = JSON.parse(data);
+    }
+    catch { }
+    if (state.chat_id === userId) {
+        return;
+    }
+    state.chat_id = userId;
+    mkdirSync(stateDir, { recursive: true });
+    writeFileSync(stateFile, JSON.stringify(state, null, 2), { mode: 0o600 });
+    p.log.success("Chat ID registered");
+}

package/dist/commands/uninstall.d.ts

@@ -0,0 +1 @@
+export declare function runUninstall(): void;

package/dist/commands/uninstall.js

@@ -0,0 +1,41 @@
+import * as p from "@clack/prompts";
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { HookInstaller } from "../hook/hook-installer.js";
+import { detectInstallMethod } from "../utils/install-detection.js";
+export function runUninstall() {
+    p.intro("🗑️  Uninstalling ccbot");
+    removeHook();
+    removeConfigDirectory();
+    printPostUninstallHint();
+    p.outro("ccbot uninstalled");
+}
+function removeHook() {
+    try {
+        HookInstaller.uninstall();
+        p.log.success("Hook removed from ~/.claude/settings.json");
+    }
+    catch {
+        p.log.warn("No hook found (already removed)");
+    }
+}
+function removeConfigDirectory() {
+    const ccbotDir = join(homedir(), ".ccbot");
+    try {
+        rmSync(ccbotDir, { recursive: true, force: true });
+        p.log.success("Removed ~/.ccbot/ (config, state, hooks)");
+    }
+    catch {
+        p.log.warn("~/.ccbot/ not found (already removed)");
+    }
+}
+function printPostUninstallHint() {
+    const method = detectInstallMethod();
+    if (method === "global") {
+        p.log.info("To also remove the package:\n  pnpm remove -g ccbot");
+    }
+    else if (method === "git-clone") {
+        p.log.info("To also remove the source:\n  rm -rf <ccbot-directory>");
+    }
+}

package/dist/commands/update.d.ts

@@ -0,0 +1 @@
+export declare function runUpdate(): void;

package/dist/commands/update.js

@@ -0,0 +1,85 @@
+import * as p from "@clack/prompts";
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { detectInstallMethod, getGitRepoRoot } from "../utils/install-detection.js";
+export function runUpdate() {
+    const method = detectInstallMethod();
+    switch (method) {
+        case "npx":
+            p.intro("📦 ccbot update");
+            p.log.step("Installed via npx — always uses latest version, no update needed.");
+            p.outro("Already up to date");
+            break;
+        case "global":
+            updateGlobal();
+            break;
+        case "git-clone":
+            updateGitClone();
+            break;
+    }
+}
+function detectGlobalPackageManager() {
+    const execPath = process.argv[1] ?? "";
+    if (execPath.includes("pnpm"))
+        return "pnpm";
+    if (execPath.includes("yarn"))
+        return "yarn";
+    if (execPath.includes("bun"))
+        return "bun";
+    return "npm";
+}
+function updateGlobal() {
+    const pm = detectGlobalPackageManager();
+    const pkg = "ccbot";
+    p.intro("📦 ccbot update");
+    const s = p.spinner();
+    s.start(`Updating via ${pm}...`);
+    const cmd = pm === "yarn"
+        ? `yarn global add ${pkg}`
+        : `${pm} install -g ${pkg}@latest`;
+    try {
+        execSync(cmd, { stdio: "pipe" });
+        s.stop("Updated successfully");
+        p.outro("Update complete");
+    }
+    catch {
+        s.stop("Update failed");
+        p.log.error(`Try manually: ${cmd}`);
+        process.exit(1);
+    }
+}
+function updateGitClone() {
+    const scriptDir = dirname(process.argv[1] ?? "");
+    const repoRoot = getGitRepoRoot(scriptDir);
+    if (!repoRoot) {
+        p.log.error("Could not find git repo root.");
+        process.exit(1);
+    }
+    p.intro("📦 ccbot update");
+    const s = p.spinner();
+    try {
+        s.start("Pulling latest changes...");
+        execSync("git pull", { cwd: repoRoot, stdio: "pipe" });
+        s.stop("Pulled latest changes");
+        const pm = existsSync(join(repoRoot, "pnpm-lock.yaml"))
+            ? "pnpm"
+            : existsSync(join(repoRoot, "yarn.lock"))
+                ? "yarn"
+                : existsSync(join(repoRoot, "bun.lockb"))
+                    ? "bun"
+                    : "npm";
+        s.start("Installing dependencies...");
+        execSync(`${pm} install`, { cwd: repoRoot, stdio: "pipe" });
+        s.stop("Dependencies installed");
+        s.start("Building...");
+        execSync(`${pm} run build`, { cwd: repoRoot, stdio: "pipe" });
+        s.stop("Build complete");
+        p.outro("Update complete");
+    }
+    catch {
+        s.stop("Update failed");
+        p.log.error("Try manually: git pull && npm install && npm run build");
+        process.exit(1);
+    }
+}

package/dist/config-manager.d.ts

@@ -0,0 +1,15 @@
+export interface Config {
+    telegram_bot_token: string;
+    user_id: number;
+    hook_port: number;
+    hook_secret: string;
+}
+export declare class ConfigManager {
+    private static readonly CONFIG_DIR;
+    private static readonly CONFIG_FILE;
+    static load(): Config;
+    static save(cfg: Config): void;
+    static isOwner(cfg: Config, userId: number): boolean;
+    static generateSecret(): string;
+    private static validate;
+}

package/dist/config-manager.js

@@ -0,0 +1,71 @@
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { randomBytes } from "node:crypto";
+export class ConfigManager {
+    static CONFIG_DIR = join(homedir(), ".ccbot");
+    static CONFIG_FILE = join(ConfigManager.CONFIG_DIR, "config.json");
+    static load() {
+        let data;
+        try {
+            data = readFileSync(ConfigManager.CONFIG_FILE, "utf-8");
+        }
+        catch (err) {
+            if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+                throw new Error("config not found — run 'ccbot setup' first");
+            }
+            throw new Error(`read config: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const raw = JSON.parse(data);
+        return ConfigManager.validate(raw);
+    }
+    static save(cfg) {
+        mkdirSync(ConfigManager.CONFIG_DIR, { recursive: true });
+        writeFileSync(ConfigManager.CONFIG_FILE, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+    }
+    static isOwner(cfg, userId) {
+        return cfg.user_id === userId;
+    }
+    static generateSecret() {
+        return randomBytes(32).toString("hex");
+    }
+    static validate(data) {
+        if (typeof data !== "object" || data === null) {
+            throw new Error("config must be a JSON object");
+        }
+        const obj = data;
+        if (typeof obj.telegram_bot_token !== "string" || !obj.telegram_bot_token.includes(":")) {
+            throw new Error("telegram_bot_token must be a string containing ':' — run 'ccbot setup'");
+        }
+        if (typeof obj.user_id !== "number" || !Number.isInteger(obj.user_id)) {
+            throw new Error("user_id must be an integer — run 'ccbot setup'");
+        }
+        let hookPort = 9377;
+        if (obj.hook_port !== undefined) {
+            if (typeof obj.hook_port !== "number" || !Number.isInteger(obj.hook_port) || obj.hook_port < 1 || obj.hook_port > 65535) {
+                throw new Error("hook_port must be an integer between 1 and 65535");
+            }
+            hookPort = obj.hook_port;
+        }
+        let hookSecret;
+        if (typeof obj.hook_secret === "string" && obj.hook_secret.length > 0) {
+            if (!/^[a-f0-9]+$/i.test(obj.hook_secret)) {
+                throw new Error("hook_secret must contain only hex characters (a-f, 0-9)");
+            }
+            hookSecret = obj.hook_secret;
+        }
+        else {
+            hookSecret = ConfigManager.generateSecret();
+        }
+        const cfg = {
+            telegram_bot_token: obj.telegram_bot_token,
+            user_id: obj.user_id,
+            hook_port: hookPort,
+            hook_secret: hookSecret,
+        };
+        if (typeof obj.hook_secret !== "string" || obj.hook_secret.length === 0) {
+            ConfigManager.save(cfg);
+        }
+        return cfg;
+    }
+}

package/dist/hook/hook-handler.d.ts

@@ -0,0 +1,9 @@
+export type NotifyFunc = (text: string) => Promise<void>;
+export declare class HookHandler {
+    private notify;
+    constructor(notify: NotifyFunc);
+    handleStopEvent(event: unknown): void;
+    private collectGitChanges;
+    private parseGitDiffOutput;
+    private parsePorcelainOutput;
+}