clearclaw 0.2.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alleriasun
+
+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,66 @@
+# ClearClaw
+
+Your coding agent, from your phone — personal assistant + project workspaces on your machine, built on the CLI's permissions, config, and memory instead of replacing them.
+
+## Why
+
+You want to talk to your coding agent from your phone. Not a chatbot — the actual agent on your actual machine, with your files, your tools, your everything.
+
+Most projects in this space add their own permission system, config format, plugin model. You end up managing two systems: the CLI you already configured, and the middleware on top.
+
+ClearClaw reuses what the CLI already has:
+
+- **No duplicate permissions.** The CLI has `settings.json` with allow/deny rules. ClearClaw relays prompts as buttons — the CLI's rules apply as-is.
+- **No duplicate config.** Your settings, MCP servers, tool allowlists — all loaded automatically. Nothing to re-configure.
+- **No duplicate memory.** `CLAUDE.md` lives in your project. The CLI loads it. ClearClaw doesn't touch it.
+- **Small and auditable.** ~1500 lines, 7 files. No plugin system, no eval, no embedded runtime.
+
+## What It Does
+
+- Routes messages between your phone and your coding agent (Telegram today, Slack planned)
+- Permission prompts with diffs, tool status, and feedback — like the terminal, on your phone
+- Maps chat groups to project workspaces — each group = a working directory
+- Personal assistant workspace for non-project conversations
+- Session continuity between terminal and phone
+
+## What It Doesn't Do
+
+- Own permissions, config, memory, or system prompts — the CLI owns those
+- Run inference or embed an agent runtime
+- Require containers, VMs, or cloud services
+- Provide a plugin or extension system
+
+## Quick Start
+
+```bash
+export TELEGRAM_BOT_TOKEN="your-bot-token"
+export ALLOWED_USER_IDS="tg:your-telegram-id"
+
+npx clearclaw
+```
+
+Or install globally: `npm install -g clearclaw`
+
+Optional: `PERMISSION_MODE` (`default` | `acceptEdits` | `bypassPermissions` | `plan`), `CLEARCLAW_HOME` (default `~/.clearclaw`).
+
+## Architecture
+
+Two interfaces keep the core thin: **Channels** (Telegram, Slack, ...) handle messaging, **Engines** (Claude Code, Codex, Kiro, ...) handle the agent. The orchestrator routes between them — adding a channel or engine means adding a file. Details in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
+
+## Prior Art
+
+| Project | Description |
+|---------|-------------|
+| [Claude Code Remote Control](https://docs.anthropic.com/en/docs/claude-code/remote-control) | Anthropic's first-party `/rc`. Max-only, single session, no daemon. |
+| [OpenClaw](https://github.com/openclaw/openclaw) | Full monolith with plugin system. [Security concerns](https://github.com/openclaw/openclaw/security). |
+| [NanoClaw](https://github.com/qwibitai/nanoclaw) | Container-isolated, multi-channel. |
+| [remotecode](https://github.com/kcisoul/remotecode) | Telegram relay with HITL permissions. |
+| [Claude-Code-Remote](https://github.com/JessyTsui/Claude-Code-Remote) | Multi-channel: Telegram, Discord, Email, LINE. |
+| [claude-telegram-relay](https://github.com/godagoo/claude-telegram-relay) | Minimal Telegram daemon. |
+| [Happy Coder](https://happy.engineering/) | Native apps, E2EE, multi-session. Polished, closed-source. |
+| [Paseo](https://paseo.sh/) | Agent-agnostic daemon (Claude Code, Codex, OpenCode). E2EE. |
+| [yottoCode](https://yottocode.com/) | Native macOS + Telegram, voice I/O. |
+
+## License
+
+[MIT](LICENSE)

package/dist/channel/slack.d.ts

@@ -0,0 +1,29 @@
+import { EventEmitter } from "node:events";
+import type { Channel, Button, ButtonResponse, SendMessageOpts } from "../types.js";
+export declare class SlackChannel extends EventEmitter implements Channel {
+    name: string;
+    private app;
+    private botToken;
+    private botUserId;
+    private allowedUserIds;
+    private pendingButtonCallbacks;
+    private pendingModalCallbacks;
+    private typingMessageTs;
+    private userNameCache;
+    constructor(botToken: string, appToken: string, allowedUserIds: Set<string>);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    ownsId(chatId: string): boolean;
+    sendMessage(chatId: string, text: string, opts?: SendMessageOpts): Promise<string[]>;
+    sendInteractive(chatId: string, text: string, buttons: Button[][]): Promise<ButtonResponse>;
+    editMessage(chatId: string, handle: string, text: string): Promise<void>;
+    deleteMessage(chatId: string, handle: string): Promise<void>;
+    pinMessage(chatId: string, handle: string): Promise<void>;
+    unpinAllMessages(chatId: string): Promise<void>;
+    updateStatus(chatId: string, text: string): Promise<void>;
+    setTyping(chatId: string, isTyping: boolean): Promise<void>;
+    private slackId;
+    /** Download a file from Slack using bot token auth. */
+    private downloadFile;
+    private resolveUserName;
+}

package/dist/channel/slack.js

@@ -0,0 +1,402 @@
+import { EventEmitter } from "node:events";
+import { App, LogLevel } from "@slack/bolt";
+import log from "../logger.js";
+export class SlackChannel extends EventEmitter {
+    name = "slack";
+    app;
+    botToken;
+    botUserId;
+    allowedUserIds;
+    pendingButtonCallbacks = new Map(); // actionId → resolve
+    pendingModalCallbacks = new Map(); // modal callbackId → resolve
+    typingMessageTs = new Map(); // chatId → ts of bot's "typing…" placeholder
+    userNameCache = new Map();
+    constructor(botToken, appToken, allowedUserIds) {
+        super();
+        this.botToken = botToken;
+        this.allowedUserIds = allowedUserIds;
+        this.app = new App({
+            token: botToken, appToken, socketMode: true, logLevel: LogLevel.ERROR,
+        });
+    }
+    async connect() {
+        this.app.event("message", async ({ event }) => {
+            const subtype = event.subtype;
+            // Suppress topic-change system messages from our setTopic calls
+            if (subtype === "channel_topic" || subtype === "group_topic") {
+                const ts = event.ts;
+                try {
+                    await this.app.client.chat.delete({ channel: event.channel, ts });
+                }
+                catch { /* may lack permission */ }
+                return;
+            }
+            if (subtype && subtype !== "bot_message" && subtype !== "file_share")
+                return;
+            // Bolt's message event is a union of many subtypes with different shapes;
+            // inline type is simpler than importing and narrowing the full union.
+            const msg = event;
+            const chatId = `slack:${msg.channel}`;
+            const isBotMessage = !!msg.bot_id || msg.user === this.botUserId;
+            if (isBotMessage)
+                return;
+            // Need either text or files to proceed
+            if (!msg.text && (!msg.files || msg.files.length === 0))
+                return;
+            const userId = msg.user;
+            if (!userId || !this.allowedUserIds.has(`slack:${userId}`)) {
+                if (userId)
+                    log.info("[channel] ignored message from unauthorized user slack:%s", userId);
+                return;
+            }
+            // Download attached files in parallel
+            let attachments;
+            if (msg.files?.length) {
+                const downloadable = msg.files.filter((f) => f.url_private_download);
+                if (downloadable.length > 0) {
+                    const results = await Promise.allSettled(downloadable.map(async (file) => {
+                        const buffer = await this.downloadFile(file.url_private_download);
+                        return { buffer, mimeType: file.mimetype ?? "application/octet-stream", filename: file.name };
+                    }));
+                    const succeeded = results
+                        .filter((r) => r.status === "fulfilled")
+                        .map((r) => r.value);
+                    for (const r of results) {
+                        if (r.status === "rejected") {
+                            log.warn({ err: r.reason }, "[channel] failed to download Slack file");
+                        }
+                    }
+                    if (succeeded.length > 0)
+                        attachments = succeeded;
+                }
+            }
+            const userName = await this.resolveUserName(userId);
+            this.emit("message", {
+                chatId,
+                user: { id: `slack:${userId}`, name: userName ?? userId },
+                text: msg.text ?? "",
+                ...(attachments && { attachments }),
+            });
+        });
+        // Handle button presses from sendInteractive
+        this.app.action(/^ccb:/, async ({ action, body, ack }) => {
+            await ack();
+            const actionId = action.action_id;
+            const triggerId = body.trigger_id ?? "";
+            const resolve = this.pendingButtonCallbacks.get(actionId);
+            if (resolve)
+                resolve(triggerId);
+        });
+        // Handle /cc slash command — emit as /<subcommand> so orchestrator handles it
+        this.app.command("/cc", async ({ command, ack }) => {
+            await ack();
+            const subcommand = command.text.trim();
+            if (!subcommand)
+                return;
+            const chatId = `slack:${command.channel_id}`;
+            const userId = command.user_id;
+            if (!this.allowedUserIds.has(`slack:${userId}`))
+                return;
+            const userName = await this.resolveUserName(userId);
+            this.emit("message", {
+                chatId,
+                user: { id: `slack:${userId}`, name: userName ?? userId },
+                text: `/${subcommand}`,
+            });
+        });
+        // Handle modal submissions from "Deny + Note" feedback
+        this.app.view(/^ccv:/, async ({ view, ack }) => {
+            await ack();
+            const feedbackValue = view.state?.values?.feedback_block?.feedback_input?.value ?? "";
+            const resolve = this.pendingModalCallbacks.get(view.callback_id);
+            if (resolve) {
+                this.pendingModalCallbacks.delete(view.callback_id);
+                resolve(feedbackValue);
+            }
+        });
+        await this.app.start();
+        try {
+            const auth = await this.app.client.auth.test();
+            this.botUserId = auth.user_id;
+            log.info("[channel] Slack bot: %s", this.botUserId);
+        }
+        catch {
+            log.warn("[channel] Connected to Slack but failed to get bot user ID");
+        }
+    }
+    async disconnect() {
+        // Delete lingering typing placeholder messages
+        for (const [chatId, ts] of this.typingMessageTs) {
+            try {
+                await this.app.client.chat.delete({ channel: this.slackId(chatId), ts });
+            }
+            catch { /* already deleted or no permission */ }
+        }
+        this.typingMessageTs.clear();
+        await this.app.stop();
+    }
+    ownsId(chatId) { return chatId.startsWith("slack:"); }
+    async sendMessage(chatId, text, opts) {
+        const channel = this.slackId(chatId);
+        const chunks = splitMessage(text);
+        const handles = [];
+        // If a typing placeholder exists, edit the first chunk into it instead of posting new
+        const consumeTyping = opts?.consumeTyping !== false;
+        const typingTs = consumeTyping ? this.typingMessageTs.get(chatId) : undefined;
+        if (typingTs && chunks.length > 0) {
+            this.typingMessageTs.delete(chatId);
+            const firstChunk = chunks.shift();
+            const blocks = mrkdwnBlocks(firstChunk);
+            try {
+                await this.app.client.chat.update({
+                    channel, ts: typingTs, text: firstChunk, blocks,
+                });
+                handles.push(typingTs);
+            }
+            catch {
+                // Placeholder was deleted externally — fall back to posting
+                const result = await this.app.client.chat.postMessage({
+                    channel, text: firstChunk, blocks,
+                });
+                if (result.ts)
+                    handles.push(result.ts);
+            }
+        }
+        for (const chunk of chunks) {
+            const blocks = mrkdwnBlocks(chunk);
+            const result = await this.app.client.chat.postMessage({
+                channel, text: chunk, blocks,
+            });
+            if (result.ts)
+                handles.push(result.ts);
+        }
+        return handles;
+    }
+    async sendInteractive(chatId, text, buttons) {
+        const channel = this.slackId(chatId);
+        const callbackId = crypto.randomUUID().slice(0, 8);
+        // Pre-compute action IDs mapped to buttons
+        const actionEntries = [];
+        let idx = 0;
+        for (const row of buttons) {
+            for (const btn of row) {
+                actionEntries.push({ btn, actionId: `ccb:${callbackId}:${idx++}` });
+            }
+        }
+        const blocks = [
+            mrkdwnBlocks(splitMessage(text)[0])[0],
+            {
+                type: "actions",
+                elements: actionEntries.map(({ btn, actionId }) => ({
+                    type: "button",
+                    text: { type: "plain_text", text: btn.label },
+                    action_id: actionId,
+                    value: btn.value,
+                })),
+            },
+        ];
+        const result = await this.app.client.chat.postMessage({
+            channel, text, blocks,
+        });
+        const cleanupAll = () => {
+            for (const { actionId } of actionEntries) {
+                this.pendingButtonCallbacks.delete(actionId);
+            }
+        };
+        // Wait for button press (no timeout — matches CLI behavior)
+        const { button: pressed, triggerId } = await new Promise((resolve) => {
+            for (const entry of actionEntries) {
+                this.pendingButtonCallbacks.set(entry.actionId, (triggerId) => {
+                    cleanupAll();
+                    resolve({ button: entry.btn, triggerId });
+                });
+            }
+        });
+        // Update message to highlight the selected button (others become inert — no callbacks)
+        if (result.ts) {
+            const feedbackBlocks = [
+                blocks[0],
+                {
+                    type: "actions",
+                    elements: actionEntries.map(({ btn, actionId }) => ({
+                        type: "button",
+                        text: { type: "plain_text", text: btn === pressed ? `✅ ${btn.label}` : btn.label },
+                        action_id: actionId,
+                        value: btn.value,
+                    })),
+                },
+            ];
+            try {
+                await this.app.client.chat.update({
+                    channel, ts: result.ts, text, blocks: feedbackBlocks,
+                });
+            }
+            catch { /* best-effort */ }
+        }
+        if (pressed.requestText && triggerId) {
+            // Open a modal for feedback input (Slack equivalent of Telegram's force_reply)
+            const modalCallbackId = `ccv:${callbackId}`;
+            await this.app.client.views.open({
+                trigger_id: triggerId,
+                view: {
+                    type: "modal",
+                    callback_id: modalCallbackId,
+                    title: { type: "plain_text", text: "Deny with note" },
+                    submit: { type: "plain_text", text: "Submit" },
+                    blocks: [
+                        {
+                            type: "input",
+                            block_id: "feedback_block",
+                            element: {
+                                type: "plain_text_input",
+                                action_id: "feedback_input",
+                                multiline: true,
+                                placeholder: { type: "plain_text", text: "Why are you denying this action?" },
+                            },
+                            label: { type: "plain_text", text: "Note" },
+                        },
+                    ],
+                },
+            });
+            const followUpText = await new Promise((resolve) => {
+                this.pendingModalCallbacks.set(modalCallbackId, resolve);
+            });
+            if (followUpText && result.ts) {
+                try {
+                    await this.app.client.chat.postMessage({
+                        channel,
+                        text: `Denied with note:\n> ${followUpText}`,
+                        thread_ts: result.ts,
+                    });
+                }
+                catch { /* best-effort */ }
+            }
+            return { value: pressed.value, text: followUpText };
+        }
+        return { value: pressed.value };
+    }
+    async editMessage(chatId, handle, text) {
+        const chunk = splitMessage(text)[0];
+        await this.app.client.chat.update({
+            channel: this.slackId(chatId),
+            ts: handle,
+            text: chunk,
+            blocks: mrkdwnBlocks(chunk),
+        });
+    }
+    async deleteMessage(chatId, handle) {
+        await this.app.client.chat.delete({
+            channel: this.slackId(chatId),
+            ts: handle,
+        });
+    }
+    async pinMessage(chatId, handle) {
+        await this.app.client.pins.add({
+            channel: this.slackId(chatId),
+            timestamp: handle,
+        });
+    }
+    async unpinAllMessages(chatId) {
+        const channel = this.slackId(chatId);
+        try {
+            const result = await this.app.client.pins.list({ channel });
+            if (result.items) {
+                for (const item of result.items) {
+                    // The Slack API returns message.ts on pinned messages but the type defs omit it
+                    const ts = item.message?.ts;
+                    if (ts) {
+                        await this.app.client.pins.remove({ channel, timestamp: ts });
+                    }
+                }
+            }
+        }
+        catch { /* may not have permission */ }
+    }
+    async updateStatus(chatId, text) {
+        await this.app.client.conversations.setTopic({
+            channel: this.slackId(chatId),
+            topic: text,
+        });
+    }
+    async setTyping(chatId, isTyping) {
+        const channel = this.slackId(chatId);
+        if (isTyping) {
+            if (this.typingMessageTs.has(chatId))
+                return;
+            try {
+                const result = await this.app.client.chat.postMessage({
+                    channel, text: "_typing…_",
+                });
+                if (result.ts)
+                    this.typingMessageTs.set(chatId, result.ts);
+            }
+            catch { /* best-effort */ }
+        }
+        else {
+            // Delete placeholder if it wasn't consumed by sendMessage
+            const ts = this.typingMessageTs.get(chatId);
+            if (ts) {
+                this.typingMessageTs.delete(chatId);
+                try {
+                    await this.app.client.chat.delete({ channel, ts });
+                }
+                catch { /* already deleted */ }
+            }
+        }
+    }
+    slackId(chatId) {
+        return chatId.replace(/^slack:/, "");
+    }
+    /** Download a file from Slack using bot token auth. */
+    async downloadFile(url) {
+        const resp = await fetch(url, {
+            headers: { Authorization: `Bearer ${this.botToken}` },
+        });
+        if (!resp.ok)
+            throw new Error(`Slack file download failed: ${resp.status}`);
+        return Buffer.from(await resp.arrayBuffer());
+    }
+    async resolveUserName(userId) {
+        const cached = this.userNameCache.get(userId);
+        if (cached)
+            return cached;
+        try {
+            const result = await this.app.client.users.info({ user: userId });
+            const name = result.user?.real_name || result.user?.name;
+            if (name)
+                this.userNameCache.set(userId, name);
+            return name;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+function mrkdwnBlocks(text) {
+    return [{ type: "section", text: { type: "mrkdwn", text } }];
+}
+// Block Kit section.text has a 3000 char limit — the tightest Slack constraint.
+// We split at this limit so each chunk fits both the text fallback and the block.
+const MAX_TEXT = 3000;
+function splitMessage(text) {
+    if (text.length <= MAX_TEXT)
+        return [text];
+    log.warn("[channel] splitting message (%d chars) into chunks", text.length);
+    const chunks = [];
+    let remaining = text;
+    while (remaining.length > MAX_TEXT) {
+        const newlineAt = remaining.lastIndexOf("\n", MAX_TEXT);
+        if (newlineAt > 0) {
+            chunks.push(remaining.slice(0, newlineAt));
+            remaining = remaining.slice(newlineAt + 1);
+        }
+        else {
+            chunks.push(remaining.slice(0, MAX_TEXT));
+            remaining = remaining.slice(MAX_TEXT);
+        }
+    }
+    if (remaining)
+        chunks.push(remaining);
+    return chunks;
+}
+//# sourceMappingURL=slack.js.map

package/dist/channel/telegram.d.ts

@@ -3,16 +3,29 @@ import type { Channel, Button, ButtonResponse, SendMessageOpts } from "../types.
 export declare class TelegramChannel extends EventEmitter implements Channel {
     name: string;
     private bot;
+    private botToken;
     private allowedUserIds;
     private typingIntervals;
+    private statusHandles;
     private pendingCallbacks;
     private pendingTextResolvers;
     constructor(botToken: string, allowedUserIds: Set<string>);
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     ownsId(chatId: string): boolean;
-    sendMessage(chatId: string, text: string, opts?: SendMessageOpts): Promise<void>;
-    sendInteractive(chatId: string, text: string, buttons: Button[]): Promise<ButtonResponse>;
+    sendMessage(chatId: string, text: string, opts?: SendMessageOpts): Promise<string[]>;
+    sendInteractive(chatId: string, text: string, buttons: Button[][]): Promise<ButtonResponse>;
+    editMessage(chatId: string, handle: string, text: string): Promise<void>;
+    deleteMessage(chatId: string, handle: string): Promise<void>;
+    pinMessage(chatId: string, handle: string): Promise<void>;
+    unpinAllMessages(chatId: string): Promise<void>;
+    updateStatus(chatId: string, text: string): Promise<void>;
     setTyping(chatId: string, isTyping: boolean): Promise<void>;
+    /** Extract auth-checked sender info from a grammY context. Returns null if unauthorized. */
+    private extractSender;
+    /** Shared handler for photo/document messages: download, emit attachment or fallback. */
+    private handleMediaMessage;
+    /** Download a Telegram file by file_id, returning the raw buffer. */
+    private downloadFile;
     private numericId;
 }