clisbot 0.1.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Long Luong
+
+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,363 @@
+# clisbot - tmux-based Agentic Coding CLI & chat bot
+The cheapest path to high-end agentic AI for teams.
+
+`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.
+
+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. 
+
+## Why clisbot
+
+- Runs native agentic AI coding CLIs in durable tmux sessions
+- 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.
+- 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:
+
+- `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 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.
+
+## Quick Start
+
+Choose one setup path.
+
+Packaged CLI path:
+
+Requires Node 20+ in the shell where you run `clisbot`.
+
+Primary command: `clisbot`
+Short alias: `clis`
+
+1. Install globally:
+
+```bash
+npm install -g clisbot
+```
+
+2. Add the required environment variables to your shell startup file, then reload it.
+
+```bash
+# ~/.zshrc or ~/.bashrc
+export SLACK_APP_TOKEN=...
+export SLACK_BOT_TOKEN=...
+export TELEGRAM_BOT_TOKEN=...
+```
+
+```bash
+source ~/.zshrc
+# or: source ~/.bashrc
+```
+
+3. Start the service directly.
+
+```bash
+clisbot start --cli codex --bootstrap personal-assistant
+clis start --cli codex --bootstrap personal-assistant
+```
+
+If you do not want to install globally, you can also run it directly with `npx`:
+
+```bash
+npx clisbot start --cli codex --bootstrap personal-assistant
+```
+
+Local repo path:
+
+Requires Bun for development commands in this repo.
+
+1. Install dependencies.
+
+```bash
+bun install
+```
+
+2. Add the required environment variables to your shell startup file, then reload it.
+
+```bash
+# ~/.zshrc or ~/.bashrc
+export SLACK_APP_TOKEN=...
+export SLACK_BOT_TOKEN=...
+export TELEGRAM_BOT_TOKEN=...
+```
+
+```bash
+source ~/.zshrc
+# or: source ~/.bashrc
+```
+
+3. Start the service directly.
+
+```bash
+bun run start --cli codex --bootstrap personal-assistant
+```
+
+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}'`.
+On startup, `clisbot` now prints which token env names it is checking and whether each one is set or missing.
+
+## Setup Guide
+
+The easiest setup flow is:
+
+1. Clone this repo.
+2. Open Claude Code or Codex in this repo.
+3. Ask it to help you set up `clisbot`.
+
+The docs in this repo are kept current, including the [User Guide](docs/user-guide/README.md), so the agent should have enough context to walk you through setup, configuration, and troubleshooting directly inside the repo.
+
+If you prefer to configure things yourself:
+
+1. Read the full config template in [config/clisbot.json.template](config/clisbot.json.template).
+2. Copy it to `~/.clisbot/clisbot.json` and adjust channels, bindings, workspaces, and policies for your environment.
+3. Add agents through the CLI so tool defaults, startup options, and bootstrap templates stay consistent.
+4. Set the required environment variables in your shell startup file so `clisbot` can read them consistently.
+
+Channel route setup is manual by design:
+
+- fresh config does not auto-add Slack channels
+- fresh config does not auto-add Telegram groups or topics
+- add only the exact channel, group, topic, or DM routing you want to expose
+- default channel account setup lives in [docs/user-guide/channel-accounts.md](docs/user-guide/channel-accounts.md)
+
+Example agent setup:
+
+```bash
+clisbot start --cli codex --bootstrap personal-assistant
+```
+
+```bash
+clisbot agents add claude --cli claude --bootstrap team-assistant --bind telegram
+clisbot agents bootstrap claude --mode team-assistant --force
+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.
+- `agents bootstrap <agentId> --mode <personal-assistant|team-assistant>` bootstraps an existing agent workspace using the agent's configured CLI tool.
+- bootstrap runs a dry check first; if any template markdown file already exists in the workspace, it stops and asks you to rerun with `--force`.
+- Fresh channel config still points at the `default` agent. If your first agent is not named `default`, update `defaultAgentId` and any route `agentId` values in config.
+
+Custom token placeholder setup:
+
+```bash
+clisbot start \
+  --cli codex \
+  --bootstrap personal-assistant \
+  --slack-app-token CUSTOM_SLACK_APP_TOKEN \
+  --slack-bot-token CUSTOM_SLACK_BOT_TOKEN
+```
+
+- these flags are written into `~/.clisbot/clisbot.json` exactly as provided
+- you can pass either `CUSTOM_SLACK_APP_TOKEN` or `'${CUSTOM_SLACK_APP_TOKEN}'`
+- `clisbot` does not expand or print the token values during config generation
+- use them when your environment variable names differ from `SLACK_APP_TOKEN`, `SLACK_BOT_TOKEN`, or `TELEGRAM_BOT_TOKEN`
+- the env var itself still needs a real value in your shell before `clisbot start` can launch
+
+Examples:
+
+```bash
+# ~/.bashrc
+export SLACK_APP_TOKEN=...
+export SLACK_BOT_TOKEN=...
+export TELEGRAM_BOT_TOKEN=...
+```
+
+```bash
+# ~/.zshrc
+export SLACK_APP_TOKEN=...
+export SLACK_BOT_TOKEN=...
+export TELEGRAM_BOT_TOKEN=...
+```
+
+```bash
+# custom names are also valid
+export CUSTOM_SLACK_APP_TOKEN=...
+export CUSTOM_SLACK_BOT_TOKEN=...
+export CUSTOM_TELEGRAM_BOT_TOKEN=...
+```
+
+Then reload your shell:
+
+```bash
+source ~/.bashrc
+```
+
+```bash
+source ~/.zshrc
+```
+
+## Troubleshooting
+
+- If setup feels unclear, open Claude Code or Codex in this repo and ask it to help using the local docs.
+- If you are still in doubt, clone `https://github.com/longbkit/clisbot`, open the repo in Codex or Claude Code, and ask questions about setup or the bootstrap mode choice.
+- If config behavior is confusing, inspect [config/clisbot.json.template](config/clisbot.json.template) first, then compare it with [docs/user-guide/README.md](docs/user-guide/README.md).
+- If `clisbot start` says no agents are configured, prefer `clisbot start --cli codex --bootstrap personal-assistant`.
+- If `clisbot start` says no default tokens were found, set Slack or Telegram tokens first using [docs/user-guide/channel-accounts.md](docs/user-guide/channel-accounts.md).
+- If `clisbot start` prints token refs as `missing`, set those exact env vars in `~/.bashrc` or `~/.zshrc`, reload the shell, then start again.
+- If you use custom env names, pass them explicitly with `--slack-app-token`, `--slack-bot-token`, or `--telegram-bot-token`.
+- If `clisbot status` shows `bootstrap=...:missing`, the workspace is missing the tool-specific bootstrap file or `IDENTITY.md`; run `clisbot agents bootstrap <agentId> --mode <mode>`.
+- If `clisbot status` shows `bootstrap=...:not-bootstrapped`, finish the workspace bootstrap by reviewing `BOOTSTRAP.md`, `SOUL.md`, `IDENTITY.md`, and the mode-specific files in that workspace.
+- If Codex shows `Do you trust the contents of this directory?`, keep `trustWorkspace: true` in clisbot config and also mark the workspace as trusted in `~/.codex/config.toml`, for example:
+
+```toml
+[projects."/home/node/.clisbot/workspaces/default"]
+trust_level = "trusted"
+```
+
+- If that trust screen is still blocking, attach directly and continue from tmux with `tmux -S ~/.clisbot/state/clisbot.sock attach -t agent-default-main`.
+- If Codex warns that `bubblewrap` is missing on Linux, install `bubblewrap` in the runtime environment.
+- If the bot does not answer, check that your shell environment really contains the expected tokens and restart `clisbot` after changing them.
+- If runtime startup still fails, run `clisbot logs` and inspect the recent log tail that `clisbot` now prints automatically on startup failure.
+- If you need the full command list, run `clisbot --help`.
+- If you need step-by-step operator docs, start with [docs/user-guide/README.md](docs/user-guide/README.md).
+- If Slack thread behavior feels too eager, use `/followup pause` or `/followup mention-only`.
+- If Slack slash commands conflict with Slack-native command handling, add a leading space, for example ` /bash ls -la`.
+
+## Commands
+
+- `clisbot start`
+- `clisbot restart`
+- `clisbot stop`
+- `clisbot stop --hard`
+- `clisbot status`
+- `clisbot logs`
+- `clisbot channels enable slack`
+- `clisbot channels enable telegram`
+- `clisbot channels add telegram-group <chatId> [--topic <topicId>] [--agent <id>] [--require-mention true|false]`
+- `clisbot channels remove telegram-group <chatId> [--topic <topicId>]`
+- `clisbot channels add slack-channel <channelId> [--agent <id>] [--require-mention true|false]`
+- `clisbot channels remove slack-channel <channelId>`
+- `clisbot channels add slack-group <groupId> [--agent <id>] [--require-mention true|false]`
+- `clisbot channels remove slack-group <groupId>`
+- `clisbot channels set-token <slack-app|slack-bot|telegram-bot> <value>`
+- `clisbot channels clear-token <slack-app|slack-bot|telegram-bot>`
+- `clisbot channels privilege enable <target>`
+- `clisbot channels privilege disable <target>`
+- `clisbot channels privilege allow-user <target> <userId>`
+- `clisbot channels privilege remove-user <target> <userId>`
+- `clisbot agents list --bindings`
+- `clisbot start --cli codex --bootstrap personal-assistant`
+- `clisbot agents bootstrap default --mode personal-assistant`
+- `clisbot agents bind --agent default --bind telegram`
+- `clisbot agents bindings`
+- `clisbot --help`
+- `bun run dev`
+- `bun run start`
+- `bun run restart`
+- `bun run stop`
+- `bun run typecheck`
+- `bun run test`
+- `bun run check`
+
+## In Chat
+
+`clisbot` supports a small set of chat-native commands for thread control, transcript access, and quick shell execution.
+
+Slack note:
+
+- To stop Slack from interpreting a slash command as a native Slack slash command, prefix it with a space.
+- Example: ` /bash ls -la`
+- Bash shorthand also works: `!ls -la`
+
+Common commands:
+
+- `/start`: show onboarding or route-status help for the current conversation.
+- `/help`: show the available clisbot conversation commands.
+- `/status`: show the current route status, follow-up policy, and operator setup hints.
+- `/whoami`: show the current sender and route identity for the active conversation.
+- `/stop`: interrupt the current running turn.
+- `/followup status`: show the current thread follow-up mode.
+- `/followup auto`: allow natural in-thread follow-up after the bot has replied.
+- `/followup mention-only`: require an explicit mention for later turns in the thread.
+- `/followup pause`: pause passive follow-up so the bot does not keep interrupting the thread unless explicitly mentioned again.
+- `/followup resume`: restore the default follow-up behavior for that conversation.
+- `/transcript`: return the current conversation transcript when privilege commands are enabled on the route.
+- `::transcript` or `\transcript`: transcript shortcuts from the default slash-style prefixes.
+- `/bash <command>`: run a shell command in the current agent workspace when sensitive commands are enabled.
+- `!<command>`: shorthand for `/bash <command>`.
+
+Command prefix defaults:
+
+- slash-style shortcuts: `["::", "\\"]`
+- bash shortcuts: `["!"]`
+- both are configurable with `channels.slack.commandPrefixes` and `channels.telegram.commandPrefixes`
+
+Sensitive commands are disabled by default:
+
+- enable them per route with `clisbot channels privilege enable ...`
+- optionally restrict them to specific users with `clisbot channels privilege allow-user ...`
+- DM examples: `clisbot channels privilege enable slack-dm` or `clisbot channels privilege enable telegram-dm`
+- use `clisbot channels --help` for the route and privilege command guide
+
+Follow-up behavior matters in team threads:
+
+- `auto` is convenient when a thread is actively collaborating with the bot.
+- `pause` is useful when the bot has already participated but you do not want it to keep jumping into every follow-up message.
+- `mention-only` is the stricter mode when you want every new bot turn to require an explicit call.
+
+## Docs
+
+- [Overview](docs/overview/README.md)
+- [Architecture](docs/architecture/README.md)
+- [Feature Tables](docs/features/feature-tables.md)
+- [Backlog](docs/tasks/backlog.md)
+- [User Guide](docs/user-guide/README.md)
+
+## Roadmap
+
+- Webhook and OpenAI-compatible completion API to integrate with more workflows.
+- Heartbeat and cronjob support, with the note that Claude already has a useful cronjob path today through loop-style workflows.
+- Autodrive / hardwork mode.
+- Support more native CLIs such as Gemini, OpenCode, and others.
+- Experiment with json output mode from codex / claude code, Agent Client Protocol and native Codex SDK integration.
+- Experiment with native messaging tools so the bot can send Slack or Telegram messages through MCP or CLI-based skills instead of tmux pane capture, for more stable and natural public-facing behavior over time.
+- Add more channels on demand.
+
+## Completed
+
+- [x] Multiple Codex and Claude sessions with streaming on/off support.
+- [x] Stale tmux session cleanup and session resume.
+- [x] OpenClaw-compatible configuration system.
+- [x] Slack channel support with streaming and attachments, smart follow mode
+- [x] Telegram channel support with streaming and attachments
+
+## AI-Native Workflow
+
+This repo also serves as a small example of an AI-native engineering workflow:
+
+- simple `AGENTS.md` and `CLAUDE.md`-style operating rules, short but addresses some common drawbacks of AI models as of 2026
+- lessons-learned docs to capture repeated feedback and pitfalls
+- architecture docs used as a stable implementation contract
+- end-to-end validation expectations to close the feedback loop for AI agents
+
+## Contributing
+
+Merge requests are welcome.
+
+MRs with real tests, screenshots, or recordings of the behavior under test will be merged faster.

package/bin/clis

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "../dist/main.js";

package/bin/clisbot

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "../dist/main.js";

package/config/clisbot.json.template

@@ -0,0 +1,173 @@
+{
+  "meta": {
+    "schemaVersion": 1,
+    "lastTouchedAt": "2026-04-07T00:00:00.000Z"
+  },
+  "tmux": {
+    "socketPath": "~/.clisbot/state/clisbot.sock"
+  },
+  "session": {
+    "mainKey": "main",
+    "dmScope": "main",
+    "identityLinks": {},
+    "storePath": "~/.clisbot/state/sessions.json"
+  },
+  "agents": {
+    "defaults": {
+      "workspace": "~/.clisbot/workspaces/{agentId}",
+      "runner": {
+        "command": "codex",
+        "args": [
+          "--dangerously-bypass-approvals-and-sandbox",
+          "--no-alt-screen",
+          "-C",
+          "{workspace}"
+        ],
+        "trustWorkspace": true,
+        "startupDelayMs": 3000,
+        "promptSubmitDelayMs": 150,
+        "sessionId": {
+          "create": {
+            "mode": "runner",
+            "args": []
+          },
+          "capture": {
+            "mode": "status-command",
+            "statusCommand": "/status",
+            "pattern": "\\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\\b",
+            "timeoutMs": 5000,
+            "pollIntervalMs": 250
+          },
+          "resume": {
+            "mode": "command",
+            "args": [
+              "resume",
+              "{sessionId}",
+              "--dangerously-bypass-approvals-and-sandbox",
+              "--no-alt-screen",
+              "-C",
+              "{workspace}"
+            ]
+          }
+        }
+      },
+      "stream": {
+        "captureLines": 160,
+        "updateIntervalMs": 2000,
+        "idleTimeoutMs": 6000,
+        "noOutputTimeoutMs": 20000,
+        "maxRuntimeMin": 15,
+        "maxMessageChars": 3500
+      },
+      "session": {
+        "createIfMissing": true,
+        "staleAfterMinutes": 60,
+        "name": "{sessionKey}"
+      }
+    },
+    "list": []
+  },
+  "bindings": [],
+  "control": {
+    "configReload": {
+      "watch": true,
+      "watchDebounceMs": 250
+    }
+  },
+  "channels": {
+    "slack": {
+      "enabled": true,
+      "mode": "socket",
+      "appToken": "${SLACK_APP_TOKEN}",
+      "botToken": "${SLACK_BOT_TOKEN}",
+      "ackReaction": "",
+      "typingReaction": "",
+      "processingStatus": {
+        "enabled": true,
+        "status": "Working...",
+        "loadingMessages": []
+      },
+      "allowBots": false,
+      "replyToMode": "thread",
+      "channelPolicy": "allowlist",
+      "groupPolicy": "allowlist",
+      "defaultAgentId": "default",
+      "privilegeCommands": {
+        "enabled": false,
+        "allowUsers": []
+      },
+      "commandPrefixes": {
+        "slash": [
+          "::",
+          "\\"
+        ],
+        "bash": [
+          "!"
+        ]
+      },
+      "streaming": "all",
+      "response": "final",
+      "followUp": {
+        "mode": "auto",
+        "participationTtlMin": 5
+      },
+      "channels": {},
+      "groups": {},
+      "directMessages": {
+        "enabled": true,
+        "policy": "pairing",
+        "allowFrom": [],
+        "requireMention": false,
+        "agentId": "default",
+        "privilegeCommands": {
+          "enabled": false,
+          "allowUsers": []
+        }
+      }
+    },
+    "telegram": {
+      "enabled": true,
+      "mode": "polling",
+      "botToken": "${TELEGRAM_BOT_TOKEN}",
+      "allowBots": false,
+      "groupPolicy": "allowlist",
+      "defaultAgentId": "default",
+      "privilegeCommands": {
+        "enabled": false,
+        "allowUsers": []
+      },
+      "commandPrefixes": {
+        "slash": [
+          "::",
+          "\\"
+        ],
+        "bash": [
+          "!"
+        ]
+      },
+      "streaming": "all",
+      "response": "final",
+      "followUp": {
+        "mode": "auto",
+        "participationTtlMin": 5
+      },
+      "polling": {
+        "timeoutSeconds": 20,
+        "retryDelayMs": 1000
+      },
+      "groups": {},
+      "directMessages": {
+        "enabled": true,
+        "policy": "pairing",
+        "allowFrom": [],
+        "requireMention": false,
+        "allowBots": false,
+        "agentId": "default",
+        "privilegeCommands": {
+          "enabled": false,
+          "allowUsers": []
+        }
+      }
+    }
+  }
+}