tabclaw 0.1.0 → 0.1.2

package/README.md

@@ -1,13 +1,28 @@
 # Tabclaw
 
-Tabclaw is a local gateway for AI assistant event hooks and notification channels. It helps connect hook-enabled agents to channels like Telegram while keeping runtime state under `~/.tabclaw`.
+Tabclaw is a local gateway that bridges AI programming assistants (like Claude Code) with chat platforms (like Telegram). It listens for agent events and forwards them to your channels in real time.
 
 ## What it does
 
-- Runs a local gateway daemon for hook-based agent integrations
-- Attaches supported agents such as `claude` to the gateway
-- Routes session events, permission requests, and status updates to configured channels
-- Provides CLI commands for daemon control, status, logs, and agent attachment
+### Overview
+
+- Runs a local HTTP gateway daemon to capture agent hook events
+- Attaches hook-enabled agents to the gateway for event streaming
+- Routes session events, permission requests, and task notifications to configured channels
+- Manages agent-initiated tool execution permissions via chat platform interactions
+
+### Claude Code + Telegram integration
+
+The core workflow bridges Claude Code with Telegram:
+
+1. **Session Monitoring** — Tabclaw listens for Claude Code session start/end events and notifies you on Telegram
+2. **Permission Control** — When Claude requests to execute a tool, you receive a permission prompt on Telegram with **Allow/Deny** buttons
+3. **Real-time Decisions** — Click the button in Telegram to grant or deny the tool execution
+4. **Task Completion** — Receive final notifications when tasks complete, including execution duration, token usage, and results
+
+![Claude + Telegram workflow](assets/image_01.jpg)
+
+![Permission request and task completion on Telegram](assets/image_02.jpg)
 
 ## Installation
 
@@ -61,9 +76,30 @@ tabclaw gateway status
 
 ## Configuration
 
-Copy `config.example.toml` to `~/.tabclaw/config.toml` and fill in your values.
+Most configuration is handled by `tabclaw init` interactive wizard, which guides you through:
+
+1. Setting up your Claude Code hook server port
+2. Configuring Telegram bot credentials
+3. Testing channel connectivity
+
+For manual setup or advanced options, edit `~/.tabclaw/config.toml`. Key sections:
+
+**General settings:**
+- `default_agent` — default agent to use (currently `claude`)
+- `hook_server_port` — local port for receiving agent hooks (default `9876`)
+- `log_level` — logging verbosity (`debug`, `info`, `warn`, `error`)
+
+**Telegram channel:**
+- `bot_token` — your Telegram bot token from BotFather
+- `allowed_users` — list of Telegram user IDs allowed to interact with the bot (e.g., `[123456789, 987654321]`)
+- `notify_types` — which event types to forward (`permission_request`, `finished`, `session_start`, `error`, etc.)
+
+**Claude agent:**
+- `adapter` — integration method (always `hooks`)
+- `binary` — Claude Code binary name
+- `permission_mode` — how to handle tool permissions
 
-Example:
+Example `~/.tabclaw/config.toml`:
 
 ```toml
 [general]
@@ -74,7 +110,8 @@ hook_server_port = 9876
 [channel.telegram]
 enabled = true
 bot_token = "YOUR_BOT_TOKEN"
-allowed_users = [123456789]
+allowed_users = ["123456789"]
+notify_types = ["permission_request", "finished", "session_start", "error"]
 
 [agent.claude]
 adapter = "hooks"

package/dist/cli/index.js

@@ -95,6 +95,16 @@ function getOrCreateHookToken() {
 function getHookToken() {
   return loadCredentials()?.hookToken ?? null;
 }
+function resetCredentials() {
+  const newToken = generateToken();
+  const credentials = {
+    version: CREDENTIALS_VERSION,
+    hookToken: newToken,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  saveCredentials(credentials);
+  return newToken;
+}
 
 // src/cli/attach.ts
 import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync2, mkdirSync } from "fs";
@@ -235,6 +245,7 @@ var en_default = {
       detected: "Claude Code detected.",
       hooksInstalled: "Hooks already installed.",
       hooksNotInstalled: "Hooks not installed.",
+      hooksTokenMismatch: "Hooks have outdated token - reconfiguration required.",
       actionQuestion: "Select action:",
       injectAction: "Inject hooks configuration",
       updateAction: "Update hooks configuration",
@@ -603,44 +614,75 @@ function detectClaude() {
       settingsPath
     };
   }
+  const currentToken = getHookToken();
   let hooked = false;
+  let tokenMismatch = false;
   if (existsSync4(settingsPath)) {
     try {
       const settings = JSON.parse(readFileSync4(settingsPath, "utf-8"));
-      hooked = isTabclawHooked(settings);
+      const hookStatus = checkTabclawHooks(settings, currentToken);
+      hooked = hookStatus.matched;
+      tokenMismatch = hookStatus.mismatched;
     } catch {
     }
   }
+  let message;
+  if (hooked) {
+    message = "Claude Code hooks already configured.";
+  } else if (tokenMismatch) {
+    message = "Claude Code hooks have mismatched token. Reconfiguration required.";
+  } else {
+    message = "Claude Code detected.";
+  }
   return {
     supported: true,
     hooked,
-    message: hooked ? "Claude Code hooks already configured." : "Claude Code detected.",
+    tokenMismatch,
+    message,
     binaryPath,
     settingsPath
   };
 }
-function isTabclawHooked(settings) {
+function checkTabclawHooks(settings, expectedToken) {
   const hooks = settings.hooks;
-  if (!hooks) return false;
+  if (!hooks) return { matched: false, mismatched: false };
+  let hasAnyTabclawHook = false;
+  let hasMatchingToken = false;
   for (const key of Object.keys(hooks)) {
     const entries = hooks[key];
     for (const entry of entries) {
       if (!entry || typeof entry !== "object") continue;
       const e = entry;
       const inner = e.hooks;
-      if (Array.isArray(inner) && inner.some((h) => isHttpHookWithTabclawUrl(h))) {
-        return true;
+      if (Array.isArray(inner)) {
+        for (const h of inner) {
+          const hookInfo = extractTabclawHookInfo(h);
+          if (hookInfo.isTabclaw) {
+            hasAnyTabclawHook = true;
+            if (expectedToken && hookInfo.token === expectedToken) {
+              hasMatchingToken = true;
+            }
+          }
+        }
       }
     }
   }
-  return false;
+  return {
+    matched: hasMatchingToken,
+    mismatched: hasAnyTabclawHook && !hasMatchingToken
+  };
 }
-function isHttpHookWithTabclawUrl(entry) {
-  if (!entry || typeof entry !== "object") return false;
+function extractTabclawHookInfo(entry) {
+  if (!entry || typeof entry !== "object") return { isTabclaw: false };
   const e = entry;
-  if (e.type !== "http") return false;
+  if (e.type !== "http") return { isTabclaw: false };
   const url = e.url;
-  return typeof url === "string" && url.includes("localhost") && url.includes("/hook/");
+  if (typeof url !== "string") return { isTabclaw: false };
+  const match = url.match(/^http:\/\/localhost:\d+\/hook\/([^\/]+)/);
+  if (match) {
+    return { isTabclaw: true, token: match[1] };
+  }
+  return { isTabclaw: false };
 }
 
 // src/cli/wizard/prompts.ts
@@ -745,6 +787,8 @@ ${t("wizard.section.cli")}
     console.log(pc.gray(`  Gateway: http://localhost:${port}/hook/${token ? token.substring(0, 8) + "..." : "unknown"}`));
     if (detection.hooked) {
       console.log(pc.green(`  ${t("wizard.cli.hooksInstalled")}`));
+    } else if (detection.tokenMismatch) {
+      console.log(pc.red(`  ${t("wizard.cli.hooksTokenMismatch")}`));
     } else {
       console.log(pc.yellow(`  ${t("wizard.cli.hooksNotInstalled")}`));
     }
@@ -874,7 +918,10 @@ async function stepCliMenu(state) {
 ${t("wizard.section.cli")}
 `));
   const cliStatus = state.itemStatus.get("claude") || "unconfigured";
-  const label = getChannelStatusLabel(cliStatus);
+  let label = getChannelStatusLabel(cliStatus);
+  if (state.claudeDetection?.tokenMismatch) {
+    label = pc2.yellow("[update needed]");
+  }
   const choice = await prompts.channelMenuSelect([{
     name: "claude",
     status: label
@@ -1323,6 +1370,11 @@ var initCommand = new Command2("init").description("Initialize tabclaw configura
       return;
     }
   }
+  if (options.force) {
+    resetCredentials();
+  } else {
+    getOrCreateHookToken();
+  }
   const wizard = new WizardEngine();
   await wizard.run();
 });