clisbot 0.1.17 → 0.1.20

package/README.md

@@ -7,34 +7,47 @@ Want to use OpenClaw but are struggling because:
 
 `clisbot` is the right solution for you.
 
-`clisbot` turns native frontier agent CLIs like Claude Code, Codex, and Gemini CLI into durable Slack and Telegram bots. Each agent runs inside its own tmux session, keeps a real workspace, and can behave like a coding bot, a daily-work assistant, or a team assistant with SOUL, IDENTITY, and MEMORY. It is not just a tmux bridge with chat glued on top. `clisbot` adds channel-aware routing, durable conversation state, pairing and access control, follow-up behavior, and support for sending and receiving files through Slack and Telegram.
+`clisbot` turns native frontier agent CLIs like Claude Code, Codex, and Gemini CLI into durable Slack and Telegram bots. Each agent runs inside its own tmux session, keeps a real workspace, and can behave like a coding bot, a daily-work assistant, or a team assistant with SOUL, IDENTITY, and MEMORY.
 
-It is a cheaper, simpler path to frontier agent workflows for teams and individuals because it reuses the CLI subscriptions you already have instead of forcing a separate API-heavy stack. If you already trust Claude Code, Codex, or Gemini CLI for real work, `clisbot` lets you keep those tools as the core runtime and add chat surfaces, follow-up control, team workflows, and on-the-go access around them.
+It is not just a tmux bridge with chat glued on top. `clisbot` treats Slack and Telegram as real channel surfaces with routing, durable conversation state, pairing, follow-up control, file sending and receiving, and the ability to keep frontier coding agents inside the tools and communication surfaces where teams already work.
 
 `clisbot` is also 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.
 
+## Why I Built This
+
+I’m Long Luong (Long), Co-founder & CTO of Vexere, Vietnam’s #1 transportation booking platform, where we also build SaaS and inventory distribution infrastructure for transportation operators. As we scale a 300-person company with a 100-member Engineering, Product, and Design team, I’ve been searching for the most practical way to roll out AI-native workflows across the organization.
+
+The challenge is not whether AI is useful. It is how to make it work at enterprise scale without creating a fragmented, expensive, or ungovernable stack. In practice, that means solving several hard problems at once: cost control, workflow truthfulness, team accessibility, governance, and the ability to bring frontier AI into the real tools and communication surfaces where work already happens.
+
+`clisbot` is the approach I landed on. Instead of building yet another isolated AI layer, it turns the coding CLIs we already trust into durable, chat-native agents that can work across Slack, Telegram, and real team workflows.
+
 ## Why clisbot
 
 - One frontier-agent stack for both daily work and real coding. You do not need one product for assistant work and another for actual engineering work.
-- Learns from and integrates the two biggest strengths that made OpenClaw popular: memory and native channel integration with deep, channel-specific conversation and presentation capabilities.
 - Reuses native CLI subscriptions you already pay for, such as Claude Code, Codex, and Gemini CLI, instead of pushing you toward a separate API-cost-heavy stack.
-- Strong chat-first support in Slack and Telegram, with durable tmux-backed sessions behind the bot, so you can work from your laptop or on the go without giving up a real coding workspace.
-- Not just a tmux bridge. Slack and Telegram are treated as real channel surfaces with routing, thread or topic continuity, pairing, follow-up control, and attachment-aware interaction instead of plain text passthrough.
-- Files and images can move through the chat surfaces too, not just text prompts: inbound Slack or Telegram attachments can land in the workspace, and outbound channel delivery is designed around real message and media actions rather than terminal-only output.
+- Learns from and integrates the two biggest strengths that made OpenClaw popular: memory and native channel integration with deep, channel-specific conversation and presentation capabilities.
+- Not just a tmux bridge. Slack and Telegram are treated as real channel surfaces with routing, thread or topic continuity, pairing, follow-up control, and attachment-aware interaction instead of plain text passthrough so you can work from your laptop or on the go without giving up a real coding workspace.
 - Team-first by design, with `AGENTS`, `USER`, and `MEMORY` context bootstrapping shaped for shared team reality instead of only personal solo-assistant flows.
-- Useful for coding, operations, teamwork, and general assistant work, with fast shell shortcuts such as `!<command>` and `/bash <command>` when you need terminal-like control from chat.
+- Useful for coding, operations, teamwork, and general assistant work, with fast chat controls such as `!<command>` and `/bash <command>` for terminal-like control, `/loop` to bring loop-style automation beyond Claude, `/queue` to add follow-up prompts in the same session without interrupting the current run, and `/streaming on` to view real-time processing progress for coding tasks.
 
 ## What to expect
 
-- You can get the first Telegram bot running in one command.
+- You can get the first Telegram bot or Slack bot running in one command.
 - The first-run path creates one default agent and only enables the channels you explicitly name.
 - DMs start with pairing so access stays explicit.
 - `--persist` lets later restarts use plain `clisbot start`.
+- Streaming is disabled by default. If you want real-time coding progress in chat, turn it on from the chat surface with `/streaming on`, and turn it off any time with `/streaming off`.
 - Slack and Telegram are not treated as plain-text sinks: routed conversations can carry thread or topic identity, pairing, and file-aware workflows.
 - Advanced multi-agent setup is available later, but it is not required for day one.
 
 ## Quick Start
 
+Platform support:
+
+- Linux and macOS are the supported host environments today.
+- Native Windows is not supported yet because `clisbot` currently depends on `tmux` and Bash-based runtime flows.
+- If you use Windows, run `clisbot` inside WSL2.
+
 Most people should start here:
 
 ```bash
@@ -48,6 +61,14 @@ clisbot start \
 
 If you want to try first without persisting the token yet, just remove `--persist`.
 
+Current auth note:
+
+- DMs currently start in pairing mode by default.
+- The config shape already includes `ownerClaimWindowMinutes`, but automatic first-owner claim from the first DM is not implemented in the runtime yet.
+- Today, if you want an owner or app admin, grant that principal explicitly with `clisbot auth add-user app --role owner --user <principal>` or `clisbot auth add-user app --role admin --user <principal>`.
+- `clisbot auth --help` now covers role scopes, permission sets, and add/remove flows for users and permissions.
+- App-level auth and owner-claim semantics in [Authorization And Roles](docs/user-guide/auth-and-roles.md) describe both the current runtime reality and the remaining target-model gaps.
+
 Need the step-by-step setup docs instead of the shortest path?
 
 - Telegram: [Telegram Bot Setup](docs/user-guide/telegram-setup.md)
@@ -90,8 +111,8 @@ bun run start --cli codex --bot-type personal --telegram-bot-token <your-telegra
 First conversation path:
 
 - send a DM to the bot in Slack or Telegram
-- `clisbot` defaults DMs to pairing mode
-- the bot replies with a pairing code and approval command
+- if that principal is already app `owner` or app `admin`, pairing is bypassed and the bot should answer normally
+- otherwise, `clisbot` defaults DMs to pairing mode and replies with a pairing code plus approval command
 
 Approve it with:
 
@@ -135,7 +156,7 @@ The easiest setup flow is still:
 
 1. Install `clisbot`.
 2. Run the quick start command above.
-3. DM the bot and approve pairing.
+3. DM the bot; approve pairing unless that principal is already app `owner` or app `admin`.
 4. Only move into advanced config after the first successful run.
 
 If you want the repo-guided setup path:
@@ -219,14 +240,16 @@ Most users only need a small set of commands at first:
 - `clisbot stop`
 - `clisbot status`
 - `clisbot logs`
+- `clisbot auth show app`
+- `clisbot auth show agent-defaults`
+- `clisbot auth add-user app --role owner --user <principal>`
+- `clisbot auth add-user agent --agent <id> --role admin --user <principal>`
 - `clisbot pairing approve slack <CODE>`
 - `clisbot pairing approve telegram <CODE>`
 - `clisbot channels enable slack`
 - `clisbot channels enable telegram`
 - `clisbot channels add telegram-group <chatId> [--topic <topicId>] [--agent <id>] [--require-mention true|false]`
 - `clisbot channels add slack-channel <channelId> [--agent <id>] [--require-mention true|false]`
-- `clisbot channels privilege enable <target>`
-- `clisbot channels privilege allow-user <target> <userId>`
 - `clisbot agents list --bindings`
 - `clisbot agents bindings`
 - `clisbot --help`
@@ -245,6 +268,12 @@ If you are running from the repo instead of the global package:
 
 `clisbot` supports a small set of chat-native commands for thread control, transcript access, and quick shell execution.
 
+Native coding-CLI command compatibility:
+
+- `clisbot` only intercepts its own reserved chat commands
+- any other native Claude, Codex, or Gemini command text is forwarded to the underlying CLI unchanged
+- operator guide: [Native CLI Commands](docs/user-guide/native-cli-commands.md)
+
 Slack note:
 
 - To stop Slack from interpreting a slash command as a native Slack slash command, prefix it with a space.
@@ -263,9 +292,9 @@ Common commands:
 - `/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`: return the current conversation transcript when the route `verbose` policy allows it.
 - `::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.
+- `/bash <command>`: run a shell command in the current agent workspace when the resolved agent role allows `shellExecute`.
 - `!<command>`: shorthand for `/bash <command>`.
 
 Command prefix defaults:
@@ -274,12 +303,12 @@ Command prefix defaults:
 - bash shortcuts: `["!"]`
 - both are configurable with `channels.slack.commandPrefixes` and `channels.telegram.commandPrefixes`
 
-Sensitive commands are disabled by default:
+Sensitive actions now follow auth and route policy:
 
-- 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
+- `/transcript` depends on the route `verbose` policy
+- `/bash` depends on resolved agent auth through `shellExecute`
+- use `clisbot auth --help` to inspect scopes and mutate role users or permissions
+- use `clisbot channels --help` for route-level setup and channel policy guidance
 
 Follow-up behavior matters in team threads:
 

package/config/clisbot.json.template

@@ -198,6 +198,10 @@
       "response": "final",
       "responseMode": "message-tool",
       "additionalMessageMode": "steer",
+      "surfaceNotifications": {
+        "queueStart": "brief",
+        "loopStart": "brief"
+      },
       "verbose": "minimal",
       "followUp": {
         "mode": "auto",
@@ -244,6 +248,10 @@
       "response": "final",
       "responseMode": "message-tool",
       "additionalMessageMode": "steer",
+      "surfaceNotifications": {
+        "queueStart": "brief",
+        "loopStart": "brief"
+      },
       "verbose": "minimal",
       "followUp": {
         "mode": "auto",