@emqo/claudebridge 0.1.0

package/README.md

@@ -0,0 +1,228 @@
+# ClaudeBridge
+
+<p align="center">
+  <a href="#english">English</a> | <a href="#中文">中文</a>
+</p>
+
+---
+
+<a name="english"></a>
+
+Bridge the `claude` CLI to chat platforms (Telegram, Discord). Spawns `claude` as a subprocess with `--output-format stream-json` -- no SDK dependency, just raw CLI power.
+
+## Features
+
+- **Multi-platform**: Telegram (raw Bot API long polling) + Discord (discord.js)
+- **Streaming responses**: Real-time message editing as Claude thinks
+- **Multi-endpoint rotation**: Round-robin with auto-cooldown on 429/401/529
+- **Session persistence**: SQLite-backed session resume via `-r <session_id>`
+- **Per-user workspace isolation**: Each user gets their own working directory
+- **Memory system**: Manual + auto-summary memories per user
+- **Task & reminder system**: Create tasks, set timed reminders
+- **Natural language intent detection**: Say "remind me in 5 min to check server" — no commands needed
+  - Regex-first (zero cost, zero latency) + Claude fallback (~$0.005/call)
+- **Auto tasks**: Queue background tasks that execute when idle
+- **File uploads**: Send files to Claude for analysis
+- **Access control**: User/group whitelist
+- **Hot reload**: Edit `config.yaml`, changes apply instantly
+- **i18n**: English + Chinese
+
+## Quick Start
+
+```bash
+# Install
+npm install
+
+# Configure
+cp config.yaml.example config.yaml  # or edit config.yaml directly
+# Set your endpoints, tokens, and access whitelist
+
+# Build & run
+npm run build
+npm start
+
+# Or dev mode (hot reload)
+npm run dev
+```
+
+## Configuration
+
+All config lives in `config.yaml`:
+
+```yaml
+endpoints:
+  - name: "my-endpoint"
+    base_url: ""          # optional, for proxies
+    api_key: "sk-..."
+    model: "claude-sonnet-4-20250514"
+
+locale: en  # "zh" for Chinese
+
+agent:
+  allowed_tools: [Read, Edit, Bash, Grep, Glob, WebSearch, WebFetch]
+  permission_mode: "acceptEdits"
+  max_turns: 50
+  max_budget_usd: 2.0
+  system_prompt: ""
+  timeout_seconds: 300
+  memory:
+    enabled: true
+    auto_summary: true
+    max_memories: 50
+  intent:
+    enabled: true              # natural language intent detection
+    use_claude_fallback: true  # use Claude when regex doesn't match
+
+workspace:
+  base_dir: "./workspaces"
+  isolation: true
+
+access:
+  allowed_users: ["your_user_id"]
+  allowed_groups: []
+
+platforms:
+  telegram:
+    enabled: true
+    token: "your-bot-token"
+    chunk_size: 4000
+  discord:
+    enabled: false
+    token: ""
+    chunk_size: 1900
+```
+
+Environment variables (`.env`) work as fallback for single-endpoint setup.
+
+## Commands
+
+| Telegram | Discord | Action |
+|----------|---------|--------|
+| /new | !new | Clear session |
+| /usage | !usage | Your usage stats |
+| /allusage | !allusage | All users stats |
+| /history | !history | Recent conversations |
+| /model | !model | Endpoint info |
+| /reload | !reload | Hot reload config |
+| /remember | !remember | Save a memory |
+| /memories | !memories | List memories |
+| /forget | !forget | Clear all memories |
+| /task | !task | Add a task |
+| /tasks | !tasks | List pending tasks |
+| /done | !done | Complete a task |
+| /remind | !remind | Set a timed reminder |
+| /auto | !auto | Queue auto task |
+| /autotasks | !autotasks | List auto tasks |
+| /cancelauto | !cancelauto | Cancel auto task |
+
+## Natural Language Intent
+
+No need to type commands — just talk naturally:
+
+| Say this | Detected as |
+|----------|-------------|
+| "remind me 5 min later check server" | Reminder: 5min, check server |
+| "remind me 10 minutes later to deploy" | Reminder: 10min, deploy |
+| "add task buy groceries" | Task: buy groceries |
+| "create task: fix login bug" | Task: fix login bug |
+| "remember I prefer dark mode" | Memory: I prefer dark mode |
+| "forget all" | Clear all memories |
+| "new session" | Clear session |
+
+Regex matches first (instant, free). If no match and `use_claude_fallback` is enabled, a low-budget Claude call classifies the intent.
+
+## Architecture
+
+```
+src/index.ts              Entry point, config loading, hot reload
+src/core/
+  agent.ts                Claude CLI subprocess spawner with retry & rotation
+  config.ts               YAML config with env fallback
+  intent.ts               Hybrid intent detection (regex + Claude)
+  keys.ts                 Endpoint round-robin with cooldown
+  lock.ts                 Per-user concurrency mutex
+  store.ts                SQLite (WAL): sessions, usage, history, memories, tasks
+  permissions.ts          Whitelist access control
+  markdown.ts             Markdown → Telegram MarkdownV2
+  i18n.ts                 Internationalization (en/zh)
+src/adapters/
+  base.ts                 Adapter interface
+  telegram.ts             Telegram Bot API (raw fetch, long polling)
+  discord.ts              Discord.js (@mentions + DMs)
+```
+
+## Prerequisites
+
+- Node.js 18+
+- `claude` CLI installed and authenticated
+- Telegram bot token (from @BotFather) and/or Discord bot token
+
+## License
+
+MIT
+
+---
+
+<a name="中文"></a>
+
+# ClaudeBridge
+
+将 `claude` CLI 桥接到聊天平台（Telegram、Discord）。通过子进程方式调用 `claude --output-format stream-json`，无需 SDK，直接使用 CLI。
+
+## 功能特性
+
+- **多平台**：Telegram（原生 Bot API 长轮询）+ Discord（discord.js）
+- **流式响应**：Claude 思考时实时编辑消息
+- **多端点轮转**：Round-robin，429/401/529 自动冷却切换
+- **会话持久化**：SQLite 存储，通过 `-r <session_id>` 恢复会话
+- **用户工作区隔离**：每个用户独立工作目录
+- **记忆系统**：手动 + 自动摘要记忆
+- **任务与提醒**：创建任务、设置定时提醒
+- **自然语言意图识别**：直接说"提醒我5分钟后检查服务器"，无需打命令
+  - 正则优先（零成本零延迟）+ Claude 兜底（~$0.005/次）
+- **自动任务**：排队后台任务，空闲时自动执行
+- **文件上传**：发送文件给 Claude 分析
+- **访问控制**：用户/群组白名单
+- **热重载**：编辑 `config.yaml` 即时生效
+- **国际化**：英文 + 中文
+
+## 快速开始
+
+```bash
+npm install
+# 编辑 config.yaml，配置端点、Token、白名单
+npm run build && npm start
+# 或开发模式
+npm run dev
+```
+
+## 自然语言意图
+
+无需输入命令，直接自然对话：
+
+| 你说 | 识别为 |
+|------|--------|
+| "提醒我5分钟后检查服务器" | 提醒：5分钟后，检查服务器 |
+| "remind me 10 min later to deploy" | 提醒：10分钟后，部署 |
+| "添加任务买牛奶" | 任务：买牛奶 |
+| "记住我喜欢TypeScript" | 记忆：我喜欢TypeScript |
+| "忘记所有" | 清除所有记忆 |
+| "新会话" | 清除会话 |
+
+正则优先匹配（即时、免费）。未匹配且 `use_claude_fallback` 开启时，用低预算 Claude 调用分类意图。
+
+## 前置要求
+
+- Node.js 18+
+- `claude` CLI 已安装并认证
+- Telegram bot token（从 @BotFather 获取）和/或 Discord bot token
+
+## 许可证
+
+MIT
+
+---
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=Emqo/ClaudeBridge&type=Date)](https://star-history.com/#Emqo/ClaudeBridge&Date)

package/config.yaml.example

@@ -0,0 +1,52 @@
+endpoints:
+  - name: "default"
+    base_url: ""
+    api_key: "sk-your-api-key"
+    model: "claude-sonnet-4-20250514"
+
+locale: en  # "zh" for Chinese
+
+agent:
+  allowed_tools:
+    - Read
+    - Edit
+    - Bash
+    - Grep
+    - Glob
+    - WebSearch
+    - WebFetch
+  permission_mode: "acceptEdits"
+  max_turns: 50
+  max_budget_usd: 2.0
+  system_prompt: ""
+  cwd: ""
+  timeout_seconds: 300
+  memory:
+    enabled: true
+    auto_summary: true
+    max_memories: 50
+  intent:
+    enabled: true
+    use_claude_fallback: true
+
+workspace:
+  base_dir: "./workspaces"
+  isolation: true
+
+access:
+  allowed_users: []
+  allowed_groups: []
+
+redis:
+  enabled: false
+  url: ""
+
+platforms:
+  telegram:
+    enabled: true
+    token: "your-telegram-bot-token"
+    chunk_size: 4000
+  discord:
+    enabled: false
+    token: ""
+    chunk_size: 1900

package/dist/adapters/base.d.ts

@@ -0,0 +1,12 @@
+export interface MessageContext {
+    userId: string;
+    text: string;
+    platform: string;
+    reply: (text: string) => Promise<void>;
+}
+export interface Adapter {
+    start(): Promise<void>;
+    stop(): void;
+}
+/** Split long text into chunks respecting newlines */
+export declare function chunkText(text: string, maxLen: number): string[];

package/dist/adapters/base.js

@@ -0,0 +1,19 @@
+/** Split long text into chunks respecting newlines */
+export function chunkText(text, maxLen) {
+    if (text.length <= maxLen)
+        return [text];
+    const chunks = [];
+    let remaining = text;
+    while (remaining.length > 0) {
+        if (remaining.length <= maxLen) {
+            chunks.push(remaining);
+            break;
+        }
+        let cut = remaining.lastIndexOf("\n", maxLen);
+        if (cut <= 0)
+            cut = maxLen;
+        chunks.push(remaining.slice(0, cut));
+        remaining = remaining.slice(cut).replace(/^\n/, "");
+    }
+    return chunks;
+}

package/dist/adapters/discord.d.ts

@@ -0,0 +1,18 @@
+import { Adapter } from "./base.js";
+import { AgentEngine } from "../core/agent.js";
+import { Store } from "../core/store.js";
+import { DiscordConfig } from "../core/config.js";
+export declare class DiscordAdapter implements Adapter {
+    private engine;
+    private store;
+    private config;
+    private locale;
+    private client;
+    private reminderTimer?;
+    constructor(engine: AgentEngine, store: Store, config: DiscordConfig, locale?: string);
+    private setup;
+    private handlePrompt;
+    start(): Promise<void>;
+    stop(): void;
+    private checkReminders;
+}

package/dist/adapters/discord.js

@@ -0,0 +1,313 @@
+import { Client, GatewayIntentBits } from "discord.js";
+import { writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { chunkText } from "./base.js";
+import { reloadConfig } from "../core/config.js";
+import { t } from "../core/i18n.js";
+import { detectIntent } from "../core/intent.js";
+const EDIT_INTERVAL = 1500;
+export class DiscordAdapter {
+    engine;
+    store;
+    config;
+    locale;
+    client;
+    reminderTimer;
+    constructor(engine, store, config, locale = "en") {
+        this.engine = engine;
+        this.store = store;
+        this.config = config;
+        this.locale = locale;
+        this.client = new Client({
+            intents: [
+                GatewayIntentBits.Guilds,
+                GatewayIntentBits.GuildMessages,
+                GatewayIntentBits.MessageContent,
+                GatewayIntentBits.DirectMessages,
+            ],
+        });
+        this.setup();
+    }
+    setup() {
+        this.client.on("messageCreate", async (msg) => {
+            if (msg.author.bot)
+                return;
+            const isDM = !msg.guild;
+            const isMentioned = msg.mentions.has(this.client.user);
+            if (!isDM && !isMentioned)
+                return;
+            const groupId = msg.guild ? String(msg.guild.id) : undefined;
+            if (!this.engine.access.isAllowed(msg.author.id, groupId))
+                return;
+            const text = msg.content.replace(/<@!?\d+>/g, "").trim();
+            // Commands
+            if (text === "!help") {
+                await msg.reply(t(this.locale, "help").replaceAll("/", "!"));
+                return;
+            }
+            if (text === "!new") {
+                this.store.clearSession(msg.author.id);
+                await msg.reply(t(this.locale, "session_cleared"));
+                return;
+            }
+            if (text === "!usage") {
+                const u = this.store.getUsage(msg.author.id);
+                await msg.reply(`Requests: ${u.count}\nTotal cost: $${u.total_cost.toFixed(4)}`);
+                return;
+            }
+            if (text === "!allusage") {
+                const rows = this.store.getUsageAll();
+                if (!rows.length) {
+                    await msg.reply(t(this.locale, "no_usage"));
+                    return;
+                }
+                const out = rows.map((r) => `${r.user_id}: ${r.count} reqs, $${r.total_cost.toFixed(4)}`).join("\n");
+                await msg.reply(out);
+                return;
+            }
+            if (text === "!history") {
+                const rows = this.store.getHistory(msg.author.id, 5);
+                if (!rows.length) {
+                    await msg.reply(t(this.locale, "no_history"));
+                    return;
+                }
+                const out = rows.reverse().map((r) => {
+                    const ts = new Date(r.created_at).toLocaleString();
+                    return `[${ts}] ${r.role}: ${r.content.slice(0, 150)}`;
+                }).join("\n\n");
+                await msg.reply(out);
+                return;
+            }
+            if (text === "!model") {
+                const eps = this.engine.getEndpoints();
+                const out = `Endpoints (${eps.length}):\n` +
+                    eps.map((e) => `• ${e.name}: ${e.model || "default"}`).join("\n");
+                await msg.reply(out);
+                return;
+            }
+            if (text === "!reload") {
+                try {
+                    const c = reloadConfig();
+                    this.engine.reloadConfig(c);
+                    this.locale = c.locale;
+                    await msg.reply(t(this.locale, "config_reloaded"));
+                }
+                catch (err) {
+                    await msg.reply(t(this.locale, "reload_failed") + err.message);
+                }
+                return;
+            }
+            if (text.startsWith("!remember ")) {
+                const content = text.slice(10).trim();
+                if (!content) {
+                    await msg.reply(t(this.locale, "usage_remember").replace("/", "!"));
+                    return;
+                }
+                this.store.addMemory(msg.author.id, content);
+                await msg.reply(t(this.locale, "memory_saved"));
+                return;
+            }
+            if (text === "!memories") {
+                const mems = this.store.getMemories(msg.author.id);
+                if (!mems.length) {
+                    await msg.reply(t(this.locale, "no_memories"));
+                    return;
+                }
+                await msg.reply(mems.map(m => `[${m.source}] ${m.content}`).join("\n\n"));
+                return;
+            }
+            if (text === "!forget") {
+                this.store.clearMemories(msg.author.id);
+                await msg.reply(t(this.locale, "memories_cleared"));
+                return;
+            }
+            if (text.startsWith("!task ")) {
+                const desc = text.slice(6).trim();
+                if (!desc) {
+                    await msg.reply(t(this.locale, "usage_task").replace("/", "!"));
+                    return;
+                }
+                const id = this.store.addTask(msg.author.id, "discord", String(msg.channelId), desc);
+                await msg.reply(t(this.locale, "task_added", { id }));
+                return;
+            }
+            if (text === "!tasks") {
+                const tasks = this.store.getTasks(msg.author.id);
+                if (!tasks.length) {
+                    await msg.reply(t(this.locale, "no_tasks"));
+                    return;
+                }
+                await msg.reply(tasks.map(tk => `#${tk.id} ${tk.description}${tk.remind_at ? ` ⏰${new Date(tk.remind_at).toLocaleString()}` : ""}`).join("\n"));
+                return;
+            }
+            if (text.startsWith("!done ")) {
+                const id = parseInt(text.slice(6).trim());
+                if (isNaN(id)) {
+                    await msg.reply(t(this.locale, "usage_done").replace("/", "!"));
+                    return;
+                }
+                const ok = this.store.completeTask(id, msg.author.id);
+                await msg.reply(ok ? t(this.locale, "task_done", { id }) : t(this.locale, "task_not_found", { id }));
+                return;
+            }
+            if (text.startsWith("!remind ")) {
+                const match = text.match(/^!remind\s+(\d+)m\s+(.+)$/);
+                if (!match) {
+                    await msg.reply(t(this.locale, "usage_remind").replace("/", "!"));
+                    return;
+                }
+                const mins = parseInt(match[1]);
+                const desc = match[2].trim();
+                const remindAt = Date.now() + mins * 60000;
+                const id = this.store.addTask(msg.author.id, "discord", String(msg.channelId), desc, remindAt);
+                await msg.reply(t(this.locale, "reminder_set", { id, mins }));
+                return;
+            }
+            if (text.startsWith("!auto ")) {
+                const desc = text.slice(6).trim();
+                if (!desc) {
+                    await msg.reply(t(this.locale, "usage_auto").replace("/", "!"));
+                    return;
+                }
+                const id = this.store.addTask(msg.author.id, "discord", String(msg.channelId), desc, undefined, true);
+                await msg.reply(t(this.locale, "auto_queued", { id }));
+                return;
+            }
+            if (text === "!autotasks") {
+                const all = this.store.getAutoTasks(msg.author.id);
+                if (!all.length) {
+                    await msg.reply(t(this.locale, "no_auto_tasks"));
+                    return;
+                }
+                await msg.reply(all.map(tk => `#${tk.id} [${tk.status}] ${tk.description}`).join("\n"));
+                return;
+            }
+            if (text.startsWith("!cancelauto ")) {
+                const id = parseInt(text.slice(12).trim());
+                if (isNaN(id)) {
+                    await msg.reply(t(this.locale, "usage_cancelauto").replace("/", "!"));
+                    return;
+                }
+                this.store.markTaskResult(id, "cancelled");
+                await msg.reply(t(this.locale, "auto_cancelled", { id }));
+                return;
+            }
+            // File upload handling
+            if (msg.attachments.size > 0) {
+                const ws = join("workspaces", msg.author.id);
+                mkdirSync(ws, { recursive: true });
+                for (const [, att] of msg.attachments) {
+                    try {
+                        const resp = await fetch(att.url);
+                        const buf = Buffer.from(await resp.arrayBuffer());
+                        writeFileSync(join(ws, att.name || "upload"), buf);
+                    }
+                    catch { }
+                }
+                const names = [...msg.attachments.values()].map(a => a.name).join(", ");
+                const prompt = text || `Analyze the uploaded file(s): ${names}`;
+                await this.handlePrompt(msg, prompt);
+                return;
+            }
+            // Intent detection (before sending to Claude)
+            if (text && !text.startsWith("!") && this.engine.getIntentConfig()?.enabled !== false) {
+                const intent = await detectIntent(text, this.engine.getRotator(), this.engine.getIntentConfig());
+                if (intent.type === "reminder" && intent.minutes && intent.description) {
+                    const remindAt = Date.now() + intent.minutes * 60000;
+                    const id = this.store.addTask(msg.author.id, "discord", String(msg.channelId), intent.description, remindAt);
+                    await msg.reply(t(this.locale, "intent_reminder_set", { mins: intent.minutes, desc: intent.description, id }));
+                    return;
+                }
+                if (intent.type === "task" && intent.description) {
+                    const id = this.store.addTask(msg.author.id, "discord", String(msg.channelId), intent.description);
+                    await msg.reply(t(this.locale, "intent_task_added", { id, desc: intent.description }));
+                    return;
+                }
+                if (intent.type === "memory" && intent.description) {
+                    this.store.addMemory(msg.author.id, intent.description, "nlp");
+                    await msg.reply(t(this.locale, "intent_memory_saved", { desc: intent.description }));
+                    return;
+                }
+                if (intent.type === "forget") {
+                    this.store.clearMemories(msg.author.id);
+                    await msg.reply(t(this.locale, "memories_cleared"));
+                    return;
+                }
+                if (intent.type === "clear_session") {
+                    this.store.clearSession(msg.author.id);
+                    await msg.reply(t(this.locale, "session_cleared"));
+                    return;
+                }
+            }
+            if (!text)
+                return;
+            await this.handlePrompt(msg, text);
+        });
+    }
+    async handlePrompt(msg, text) {
+        if (this.engine.isLocked(msg.author.id)) {
+            await msg.reply(t(this.locale, "still_processing"));
+            return;
+        }
+        const placeholder = await msg.reply(t(this.locale, "thinking"));
+        let lastEdit = 0;
+        let lastText = "";
+        try {
+            const res = await this.engine.runStream(msg.author.id, text, "discord", async (_chunk, full) => {
+                const now = Date.now();
+                if (now - lastEdit < EDIT_INTERVAL)
+                    return;
+                const preview = full.slice(-1900) + "\n\n⏳...";
+                if (preview === lastText)
+                    return;
+                lastText = preview;
+                lastEdit = now;
+                try {
+                    await placeholder.edit(preview);
+                }
+                catch { }
+            });
+            const maxLen = this.config.chunk_size || 1900;
+            const chunks = chunkText(res.text, maxLen);
+            try {
+                await placeholder.edit(chunks[0]);
+            }
+            catch { }
+            for (let i = 1; i < chunks.length; i++) {
+                await msg.reply(chunks[i]);
+            }
+        }
+        catch (err) {
+            console.error("[discord] error:", err);
+            try {
+                await placeholder.edit(`Error: ${err.message || "unknown"}`);
+            }
+            catch { }
+        }
+    }
+    async start() {
+        console.log("[discord] starting bot...");
+        await this.client.login(this.config.token);
+        console.log(`[discord] logged in as ${this.client.user?.tag}`);
+        this.reminderTimer = setInterval(() => this.checkReminders(), 30000);
+    }
+    stop() {
+        if (this.reminderTimer)
+            clearInterval(this.reminderTimer);
+        this.client.destroy();
+    }
+    async checkReminders() {
+        try {
+            const due = this.store.getDueReminders().filter(r => r.platform === "discord");
+            for (const r of due) {
+                const ch = await this.client.channels.fetch(r.chat_id);
+                if (ch?.isTextBased() && "send" in ch)
+                    await ch.send(t(this.locale, "reminder_notify", { desc: r.description }));
+                this.store.markReminderSent(r.id);
+            }
+        }
+        catch (e) {
+            console.error("[discord] reminder error:", e);
+        }
+    }
+}

package/dist/adapters/telegram.d.ts

@@ -0,0 +1,27 @@
+import { Adapter } from "./base.js";
+import { AgentEngine } from "../core/agent.js";
+import { Store } from "../core/store.js";
+import { TelegramConfig } from "../core/config.js";
+export declare class TelegramAdapter implements Adapter {
+    private engine;
+    private store;
+    private config;
+    private locale;
+    private running;
+    private offset;
+    private reminderTimer?;
+    private autoTimer?;
+    private autoRunning;
+    constructor(engine: AgentEngine, store: Store, config: TelegramConfig, locale?: string);
+    private get api();
+    private call;
+    private reply;
+    private editMsg;
+    private handleUpdate;
+    private handlePrompt;
+    start(): Promise<void>;
+    stop(): void;
+    private registerCommands;
+    private checkReminders;
+    private processAutoTasks;
+}