clisbot 0.1.7 → 0.1.9

package/README.md

@@ -1,41 +1,61 @@
-# clisbot - tmux-based Agentic Coding CLI & chat bot
-The cheapest path to high-end agentic AI for teams.
+# clisbot - Agentic Coding CLI & chat bot
+The cheapest, simplest path to frontier LLMs and agentic CLI workflows for teams and individuals.
 
-`clisbot` exposes native agentic AI tool CLIs like Claude Code / Codex through chat surfaces, with each agent running inside its own durable tmux session and ready to behave like a real bot, a real assistant - with SOUL & IDENTITY, not just a coding tool.
+`clisbot` exposes native agentic AI tool CLIs like Claude Code / Codex through multi-channel chat surfaces, with each agent running inside its own durable tmux session and ready to behave like a real bot, a real assistant - with SOUL, IDENTITY & MEMORY, not just a coding tool.
+
+It is not just another tmux bridge or Telegram bridge. `clisbot` is meant to grow into a reusable agent runtime layer that can support many CLI tools, many channels, and many workflow shapes on top of the same durable agent session.
 
 Agentic AI is powerful, but only with frontier models. OpenClaw took off because people found many ways to access strong frontier models cheaply through subscription-based OAuth. Recent Anthropic enforcement around third-party and proxy-style usage made that risk harder to ignore.
 
 Meanwhile, the strongest agentic coding tools already come from serious enterprise teams with real investment in model quality, security, safety, and operator controls, especially Claude Code, Codex, and Gemini CLI. That naturally leads to a simple question: why not reuse those agents as they already are, keep them alive in tmux, and add communication channels, team workflows, and more toys around them?
 
-The idea has been stuck in my head since Claude Code introduced agent skills back in October 2025, which opened more possibilities for non-developer workers, and the OpenClaw trend recently only made it harder to ignore. Having played around with Anthropic's Agent SDK to address the agentic AI adoption inside my company but somehow it was not working, not stable, not flexible, not fast enough, and the CLI path now looks like the better choice until now. Now feels like the right time to push that idea.
-
 Every company will likely need an OpenClaw-style strategy over time: a personal agentic assistant for each employee, plus shared agents for each team. `clisbot` starts from a team-first angle, with Slack and shared agent workflows as the default center of gravity instead of treating team collaboration as a later add-on. 
 
+## Important caution
+
+Strong vendor investment in security and safety does not make frontier agentic CLI tools inherently safe. `clisbot` exposes those tools more broadly through chat and workflow surfaces, so you should treat the whole system as high-trust software and use it at your own risk.
+
+## Acknowledgements
+
+`clisbot` would not exist without the ideas, momentum, and practical inspiration created by OpenClaw. Many configuration, routing, and workspace concepts here were learned from studying OpenClaw, then adapted to `clisbot`'s own direction. Respect and thanks to the OpenClaw project and community.
+
 ## Why clisbot
 
-- Runs native agentic AI coding CLIs in durable tmux sessions
+- Reuses the native CLI tools you already know and subscribe to, such as Claude Code, Codex, and Gemini CLI, then extends them across coding, chatbot, and non-dev workflows without forcing you to switch tools.
 - Optimized for cheap subscription-backed usage with tools like Codex CLI and Claude CLI... A practical response to the reality that high-quality frontier models are expensive and vendor policies can tighten around third-party usage.
 - Compatible with OpenClaw-style configuration, commands and some concepts, agent personality for bot usecases, and workspace bootstrap templates, help Openclaw users to quickly get started.
 - Team-first by design, with agent bootstrap templates that fit shared team agents as well as personal ones.
-- Reuses mature agentic tools such as Claude Code, Codex, and Gemini CLI
 - Fits the emerging pattern of one personal assistant per employee and shared assistants per team.
 - Useful as a bot for coding, operations, teamwork, and general work in team environment, or on the go
 - Strong team support in Slack, with Telegram already supported as another first-class channel.
 - Configurable follow-up policy instead of a fixed TTL model, with a 5-minute default window and route-level controls so teams can tune behavior to how they actually work. Smart follow-up controls help avoid unwanted bot interruption in active threads: keep natural continuation when useful, or pause it when you want the bot to stay quiet until explicitly called again.
-- Fast operator shortcuts for shell execution: `!<command>` or `/bash <command>`. Turns Slack / Telegram to terminal interface on the go.
+- Fast operator shortcuts for shell execution: `!<command>` or `/bash <command>`, plus slash-prefix mappings such as `\bash` or `::bash` when Slack slash-command handling is incompatible. Turns Slack / Telegram into a terminal interface on the go.
 - The proof of concept already shows high potential beyond internal coding workflows, including customer chatbot use cases once messaging MCP or CLI-based skills let the agent send messages proactively in a cleaner way.
 
 ## Current Focus
 
-`clisbot` is a communication bridge for long-lived AI agents, organized around the repository architecture contract:
+`clisbot` is growing toward a broader agent runtime layer:
+
+- more CLI tool support beyond Claude Code and Codex, including Gemini CLI, OpenCode, Qwen, Kilo, and other agentic CLIs
+- more communication channels beyond Slack and Telegram, including Zalo, WhatsApp, Facebook, Discord, and future API-compatible surfaces
+- simple workflow building blocks such as cronjobs, heartbeat jobs, lightweight Ralph-style loops, and prompt combinations that just work
+- durable agent sessions, workspaces, follow-up policy, commands, attachments, and operator controls that stay reusable across all those surfaces
 
-- `channels`: Slack, Telegram, and future API-compatible surfaces
-- `agent-os`: agents, sessions, workspaces, commands, attachments, and follow-up policy
-- `runners`: tmux today, with ACP, SDK, and other execution backends later
-- `control`: operator-facing inspection, lifecycle, and debugging flows
-- `configuration`: the local control plane that wires the system together
+tmux is still the current stability boundary. One agent maps to one durable runner session in one workspace, and every CLI, channel, or workflow layer should route onto that durable runtime instead of recreating the agent from scratch.
 
-tmux is the current stability boundary. One agent maps to one durable runner session in one workspace, and chat surfaces route conversations onto that runtime instead of trying to recreate it.
+## Showcase
+
+Slack
+
+![Slack showcase](https://raw.githubusercontent.com/longbkit/clisbot/main/docs/pics/slack-01.jpg)
+
+Telegram
+
+![Telegram topic showcase 1](https://raw.githubusercontent.com/longbkit/clisbot/main/docs/pics/telegram-01.jpg)
+
+![Telegram topic showcase 2](https://raw.githubusercontent.com/longbkit/clisbot/main/docs/pics/telegram-02.jpg)
+
+![Telegram topic showcase 3](https://raw.githubusercontent.com/longbkit/clisbot/main/docs/pics/telegram-03.jpg)
 
 ## Quick Start
 
@@ -75,6 +95,19 @@ clisbot start --cli codex --bootstrap personal-assistant
 clis start --cli codex --bootstrap personal-assistant
 ```
 
+4. Fastest first conversation path: send a direct message to the bot in Slack or Telegram.
+
+`clisbot` defaults direct messages to pairing mode. The bot will reply with a pairing code and approval command.
+
+Approve it with:
+
+```bash
+clisbot pairing approve slack <CODE>
+clisbot pairing approve telegram <CODE>
+```
+
+After approval, keep chatting with the bot in that DM or add shared channel or topic routes later.
+
 If you do not want to install globally, you can also run it directly with `npx`:
 
 ```bash
@@ -111,6 +144,19 @@ source ~/.zshrc
 bun run start --cli codex --bootstrap personal-assistant
 ```
 
+4. Fastest first conversation path: send a direct message to the bot in Slack or Telegram.
+
+`clisbot` defaults direct messages to pairing mode. The bot will reply with a pairing code and approval command.
+
+Approve it with:
+
+```bash
+bun run pairing -- approve slack <CODE>
+bun run pairing -- approve telegram <CODE>
+```
+
+After approval, keep chatting with the bot in that DM or add shared channel or topic routes later.
+
 Fresh config now starts with no configured agents, and first-run `clisbot start` requires both `--cli` and `--bootstrap` before it creates the first `default` agent.
 Fresh config also starts with no preconfigured Slack channels or Telegram groups/topics. Add those routes manually in `~/.clisbot/clisbot.json`.
 `clisbot start` now also requires Slack or Telegram token references before it bootstraps anything. By default it looks for `SLACK_APP_TOKEN`, `SLACK_BOT_TOKEN`, and `TELEGRAM_BOT_TOKEN`, but you can pass custom placeholders such as `--slack-app-token '${CUSTOM_SLACK_APP_TOKEN}'`.
@@ -155,7 +201,6 @@ clisbot agents list --bindings
 Agent setup rules:
 
 - `agents add` requires `--cli` and currently supports `codex` and `claude`.
-- `--startup-option` is optional; if omitted, clisbot uses the built-in startup options for the selected CLI.
 - `--bootstrap` accepts `personal-assistant` or `team-assistant` and seeds the workspace from `templates/openclaw` plus the selected customized template.
 - `personal-assistant` fits one assistant for one human.
 - `team-assistant` fits one shared assistant for a team, channel, or group workflow.

package/config/clisbot.json.template

@@ -80,6 +80,18 @@
       "mode": "socket",
       "appToken": "${SLACK_APP_TOKEN}",
       "botToken": "${SLACK_BOT_TOKEN}",
+      "defaultAccount": "default",
+      "accounts": {
+        "default": {
+          "appToken": "${SLACK_APP_TOKEN}",
+          "botToken": "${SLACK_BOT_TOKEN}"
+        }
+      },
+      "agentPrompt": {
+        "enabled": true,
+        "maxProgressMessages": 3,
+        "requireFinalResponse": true
+      },
       "ackReaction": "",
       "typingReaction": "",
       "processingStatus": {
@@ -107,6 +119,8 @@
       },
       "streaming": "all",
       "response": "final",
+      "responseMode": "message-tool",
+      "additionalMessageMode": "steer",
       "followUp": {
         "mode": "auto",
         "participationTtlMin": 5
@@ -129,6 +143,17 @@
       "enabled": true,
       "mode": "polling",
       "botToken": "${TELEGRAM_BOT_TOKEN}",
+      "defaultAccount": "default",
+      "accounts": {
+        "default": {
+          "botToken": "${TELEGRAM_BOT_TOKEN}"
+        }
+      },
+      "agentPrompt": {
+        "enabled": true,
+        "maxProgressMessages": 3,
+        "requireFinalResponse": true
+      },
       "allowBots": false,
       "groupPolicy": "allowlist",
       "defaultAgentId": "default",
@@ -147,6 +172,8 @@
       },
       "streaming": "all",
       "response": "final",
+      "responseMode": "message-tool",
+      "additionalMessageMode": "steer",
       "followUp": {
         "mode": "auto",
         "participationTtlMin": 5

package/dist/main.js

@@ -51156,7 +51156,7 @@ var require_send = __commonJS((exports, module) => {
   var join6 = path2.join;
   var normalize = path2.normalize;
   var resolve = path2.resolve;
-  var sep = path2.sep;
+  var sep2 = path2.sep;
   var BYTES_RANGE_REGEXP = /^ *bytes=/;
   var MAX_MAXAGE = 60 * 60 * 24 * 365 * 1000;
   var UP_PATH_REGEXP = /(?:^|[\\/])\.\.(?:[\\/]|$)/;
@@ -51317,14 +51317,14 @@ var require_send = __commonJS((exports, module) => {
     var parts;
     if (root !== null) {
       if (path3) {
-        path3 = normalize("." + sep + path3);
+        path3 = normalize("." + sep2 + path3);
       }
       if (UP_PATH_REGEXP.test(path3)) {
         debug('malicious path "%s"', path3);
         this.error(403);
         return res;
       }
-      parts = path3.split(sep);
+      parts = path3.split(sep2);
       path3 = normalize(join6(root, path3));
     } else {
       if (UP_PATH_REGEXP.test(path3)) {
@@ -51332,7 +51332,7 @@ var require_send = __commonJS((exports, module) => {
         this.error(403);
         return res;
       }
-      parts = normalize(path3).split(sep);
+      parts = normalize(path3).split(sep2);
       path3 = resolve(path3);
     }
     if (containsDotFile(parts)) {
@@ -51427,7 +51427,7 @@ var require_send = __commonJS((exports, module) => {
     var self2 = this;
     debug('stat "%s"', path3);
     fs2.stat(path3, function onstat(err, stat) {
-      var pathEndsWithSep = path3[path3.length - 1] === sep;
+      var pathEndsWithSep = path3[path3.length - 1] === sep2;
       if (err && err.code === "ENOENT" && !extname(path3) && !pathEndsWithSep) {
         return next(err);
       }
@@ -62697,7 +62697,7 @@ function escapeRegExp(raw) {
 // src/control/clisbot-wrapper.ts
 import { chmod } from "node:fs/promises";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
-import { dirname as dirname7, join as join5 } from "node:path";
+import { dirname as dirname7, join as join5, sep } from "node:path";
 var DEFAULT_CLISBOT_BIN_DIR = join5(APP_HOME_DIR, "bin");
 var DEFAULT_CLISBOT_WRAPPER_PATH = join5(DEFAULT_CLISBOT_BIN_DIR, "clisbot");
 function shellQuote(value) {
@@ -62709,9 +62709,19 @@ function shellQuote(value) {
 function getClisbotMainScriptPath() {
   return fileURLToPath3(new URL("../main.ts", import.meta.url));
 }
+function isPackagedRuntime() {
+  const currentModulePath = fileURLToPath3(import.meta.url);
+  return currentModulePath.includes(`${sep}dist${sep}`);
+}
 function getClisbotWrapperPath() {
   return expandHomePath(process.env.CLISBOT_WRAPPER_PATH || DEFAULT_CLISBOT_WRAPPER_PATH);
 }
+function getClisbotPromptCommand() {
+  if (process.env.CLISBOT_PROMPT_COMMAND?.trim()) {
+    return process.env.CLISBOT_PROMPT_COMMAND.trim();
+  }
+  return isPackagedRuntime() ? "clis" : getClisbotWrapperPath();
+}
 function getClisbotWrapperDir() {
   return dirname7(getClisbotWrapperPath());
 }
@@ -62731,7 +62741,7 @@ async function ensureClisbotWrapper() {
   const wrapperDir = dirname7(wrapperPath);
   await ensureDir2(wrapperDir);
   const nextScript = renderClisbotWrapperScript();
-  const existing = await fileExists(wrapperPath) ? await Bun.file(wrapperPath).text() : null;
+  const existing = await fileExists(wrapperPath) ? await readTextFile(wrapperPath) : null;
   if (existing !== nextScript) {
     await writeTextFile(wrapperPath, nextScript);
   }
@@ -63247,6 +63257,41 @@ async function monitorTmuxRun(params) {
 }
 
 // src/agents/active-run-manager.ts
+var OBSERVER_RETRYABLE_FAILURE_LIMIT = 3;
+function formatObserverError(error) {
+  return error instanceof Error ? error.stack ?? error.message : String(error);
+}
+function listObserverErrorCodes(error) {
+  const codes = new Set;
+  const visit = (value) => {
+    if (!value || typeof value !== "object") {
+      return;
+    }
+    const candidate = value;
+    if (typeof candidate.code === "string" && candidate.code.trim()) {
+      codes.add(candidate.code.trim().toUpperCase());
+    }
+    if (Array.isArray(candidate.errors)) {
+      for (const nested of candidate.errors) {
+        visit(nested);
+      }
+    }
+    if (candidate.cause) {
+      visit(candidate.cause);
+    }
+  };
+  visit(error);
+  return [...codes];
+}
+function isRetryableObserverDeliveryError(error) {
+  const codes = listObserverErrorCodes(error);
+  if (codes.some((code) => code === "ETIMEDOUT" || code === "ECONNRESET" || code === "ECONNREFUSED" || code === "EHOSTUNREACH" || code === "ENETUNREACH" || code === "UND_ERR_CONNECT_TIMEOUT" || code === "UND_ERR_HEADERS_TIMEOUT" || code === "UND_ERR_SOCKET")) {
+    return true;
+  }
+  const message = error instanceof Error ? `${error.name} ${error.message}` : String(error);
+  return /fetch failed|request timed out|network|socket hang up/i.test(message);
+}
+
 class ActiveRunInProgressError extends Error {
   update;
   constructor(update) {
@@ -63322,6 +63367,7 @@ class ActiveRunManager {
       this.activeRuns.set(resolved.sessionKey, {
         resolved,
         observers: new Map,
+        observerFailures: new Map,
         initialResult,
         latestUpdate: update
       });
@@ -63356,6 +63402,7 @@ class ActiveRunManager {
     this.activeRuns.set(provisionalResolved.sessionKey, {
       resolved: provisionalResolved,
       observers: new Map([[observer.id, { ...observer }]]),
+      observerFailures: new Map,
       initialResult,
       latestUpdate: this.createRunUpdate({
         resolved: provisionalResolved,
@@ -63412,6 +63459,7 @@ class ActiveRunManager {
       existingRun.observers.set(observer.id, {
         ...observer
       });
+      existingRun.observerFailures.delete(observer.id);
       return {
         active: !isTerminalRunStatus(existingRun.latestUpdate.status),
         update: existingRun.latestUpdate
@@ -63446,6 +63494,7 @@ class ActiveRunManager {
       };
     }
     observer.mode = "passive-final";
+    run.observerFailures.delete(observerId);
     return {
       detached: true
     };
@@ -63472,7 +63521,7 @@ class ActiveRunManager {
   async notifyRunObservers(run, update) {
     run.latestUpdate = update;
     const now = Date.now();
-    for (const observer of run.observers.values()) {
+    for (const [observerId, observer] of run.observers.entries()) {
       if (observer.expiresAt && now >= observer.expiresAt && observer.mode !== "passive-final") {
         observer.mode = "passive-final";
       }
@@ -63488,7 +63537,21 @@ class ActiveRunManager {
         continue;
       }
       observer.lastSentAt = now;
-      await observer.onUpdate(update);
+      try {
+        await observer.onUpdate(update);
+        run.observerFailures.delete(observerId);
+      } catch (error) {
+        const retryable = isRetryableObserverDeliveryError(error);
+        const nextFailures = retryable ? (run.observerFailures.get(observerId) ?? 0) + 1 : OBSERVER_RETRYABLE_FAILURE_LIMIT;
+        const shouldDetach = !retryable || isTerminalRunStatus(update.status) || nextFailures >= OBSERVER_RETRYABLE_FAILURE_LIMIT;
+        if (shouldDetach) {
+          run.observers.delete(observerId);
+          run.observerFailures.delete(observerId);
+        } else {
+          run.observerFailures.set(observerId, nextFailures);
+        }
+        console.error(shouldDetach ? `run observer '${observerId}' update failed for ${run.resolved.sessionKey}; detaching observer` : `run observer '${observerId}' update failed for ${run.resolved.sessionKey}; keeping observer for retry (${nextFailures}/${OBSERVER_RETRYABLE_FAILURE_LIMIT})`, formatObserverError(error));
+      }
     }
   }
   async finishActiveRun(sessionKey, update) {
@@ -64768,9 +64831,8 @@ function renderAgentPromptInstruction(params) {
     messageToolMode ? "channel auto-delivery is disabled for this conversation; send user-facing progress updates and the final response yourself with the reply command" : "channel auto-delivery remains enabled for this conversation; do not send user-facing progress updates or the final response with clisbot message send"
   ];
   if (messageToolMode) {
-    const wrapperPath = getClisbotWrapperPath();
     const replyCommand = buildReplyCommand({
-      wrapperPath,
+      command: getClisbotPromptCommand(),
       identity: params.identity
     });
     lines.push("Use the exact command below when you need to send progress updates, media attachments, or the final response back to the user.", "reply command:", replyCommand, `progress updates: at most ${params.config.maxProgressMessages}`, params.config.requireFinalResponse ? "final response: send exactly 1 final user-facing response" : "final response: optional", "keep progress updates short and meaningful", "do not send progress updates for trivial internal steps");
@@ -64843,7 +64905,7 @@ function renderNamedValue(label, name, id) {
   return value ? `${label} ${value}` : "";
 }
 function buildReplyCommand(params) {
-  const lines = [`${params.wrapperPath} message send \\`];
+  const lines = [`${params.command} message send \\`];
   if (params.identity.platform === "slack") {
     lines.push("  --channel slack \\");
     lines.push(`  --target channel:${params.identity.channelId ?? ""} \\`);
@@ -66151,6 +66213,7 @@ class SlackSocketService {
 // src/channels/slack/message-actions.ts
 var import_bolt = __toESM(require_dist7(), 1);
 import { basename } from "node:path";
+import { readFile as readFile2 } from "node:fs/promises";
 var { WebClient } = import_bolt.webApi;
 function createSlackClient(botToken) {
   return new WebClient(botToken);
@@ -66210,13 +66273,9 @@ async function loadSlackMedia(media) {
       data: Buffer.from(arrayBuffer)
     };
   }
-  const file = Bun.file(media);
-  if (!await file.exists()) {
-    throw new Error(`Media file not found: ${media}`);
-  }
   return {
     filename: basename(media),
-    data: Buffer.from(await file.arrayBuffer())
+    data: await readFile2(media)
   };
 }
 async function sendSlackMessage(params) {
@@ -67512,6 +67571,7 @@ function resolveRouteAndTarget(params) {
 
 // src/channels/telegram/message-actions.ts
 import { basename as basename3, extname as extname2 } from "node:path";
+import { readFile as readFile3 } from "node:fs/promises";
 function parseTelegramChatId(raw) {
   const value = raw.trim();
   if (value.startsWith("@")) {
@@ -67535,13 +67595,9 @@ async function loadTelegramMedia(media) {
       remoteUrl: media
     };
   }
-  const file = Bun.file(media);
-  if (!await file.exists()) {
-    throw new Error(`Media file not found: ${media}`);
-  }
   return {
     filename: basename3(media),
-    file
+    file: new Blob([await readFile3(media)])
   };
 }
 function inferTelegramMediaKind(filename, forceDocument) {
@@ -67973,7 +68029,7 @@ import { watch } from "node:fs";
 import { basename as basename4, dirname as dirname11 } from "node:path";
 
 // src/channels/processed-events-store.ts
-import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import { mkdir as mkdir2, readFile as readFile4, writeFile as writeFile2 } from "node:fs/promises";
 var DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 var PROCESSING_STALE_MS = 30 * 60 * 1000;
 
@@ -67991,7 +68047,7 @@ class ProcessedEventsStore {
       return;
     }
     try {
-      const text = await readFile2(this.filePath, "utf8");
+      const text = await readFile4(this.filePath, "utf8");
       this.document = JSON.parse(text);
     } catch {
       this.document = { events: {} };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clisbot",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "private": false,
   "description": "Chat surfaces for durable AI coding agents running in tmux",
   "license": "MIT",