clisbot 0.1.9 → 0.1.11

package/README.md

@@ -1,9 +1,9 @@
 # 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 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.
+`clisbot` is not just another tmux bridge, as many GitHub projects already are. It 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, just as OpenClaw, 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.
+`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.
 
@@ -43,6 +43,27 @@ Strong vendor investment in security and safety does not make frontier agentic C
 
 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.
 
+## Launch MVP Path
+
+See [docs/overview/launch-mvp-path.md](docs/overview/launch-mvp-path.md) for the full current launch order.
+
+Short snapshot:
+
+1. Foundations first:
+   - frictionless start and credential persistence
+   - runtime stability and truthful status or debug UX
+   - `/loop` as the current differentiating workflow feature
+2. International launch gate:
+   - Claude, Codex, and Gemini as the well-tested core CLI trio
+   - current shared channel package remains Slack plus Telegram
+3. Vietnam launch package:
+   - add Zalo Official Account and Zalo Personal on top of the same core trio
+4. Next expansion wave:
+   - more CLIs such as Cursor, Amp, OpenCode, Qwen, Kilo, and Minimax, prioritized by real userbase demand
+   - more channels such as Discord, WhatsApp, Google Workspace, and Microsoft Teams
+5. Open launch decision:
+   - whether native CLI slash-command compatibility, override, and customization should ship before broader push
+
 ## Showcase
 
 Slack
@@ -59,108 +80,81 @@ Telegram
 
 ## 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=...
-```
+Fastest first-run path for the first Telegram bot:
 
 ```bash
-source ~/.zshrc
-# or: source ~/.bashrc
+clisbot start \
+  --cli codex \
+  --bot-type personal \
+  --telegram-bot-token <your-telegram-bot-token>
 ```
 
-3. Start the service directly.
+If you want later runs to work with plain `clisbot start`, persist that token immediately:
 
 ```bash
-clisbot start --cli codex --bootstrap personal-assistant
-clis start --cli codex --bootstrap personal-assistant
+clisbot start \
+  --cli codex \
+  --bot-type personal \
+  --telegram-bot-token <your-telegram-bot-token> \
+  --persist
 ```
 
-4. Fastest first conversation path: send a direct message to the bot in Slack or Telegram.
+What this does:
 
-`clisbot` defaults direct messages to pairing mode. The bot will reply with a pairing code and approval command.
+- `--bot-type personal` creates one assistant for one human
+- `--bot-type team` creates one shared assistant for a team, channel, or group workflow
+- literal token input stays in memory unless you also pass `--persist`
+- `--persist` promotes the token into the canonical credential file so the next `clisbot start` can reuse it without retyping
+- fresh bootstrap only enables the channels you name explicitly
+- after the persisted first run, later restarts can use plain `clisbot start`
 
-Approve it with:
+Packaged CLI path:
 
 ```bash
-clisbot pairing approve slack <CODE>
-clisbot pairing approve telegram <CODE>
+npm install -g clisbot
+clisbot start --cli codex --bot-type personal --telegram-bot-token <your-telegram-bot-token> --persist
 ```
 
-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`:
+Short alias:
 
 ```bash
-npx clisbot start --cli codex --bootstrap personal-assistant
+clis start --cli codex --bot-type personal --telegram-bot-token <your-telegram-bot-token>
 ```
 
 Local repo path:
 
-Requires Bun for development commands in this repo.
-
-1. Install dependencies.
-
 ```bash
 bun install
+bun run start --cli codex --bot-type personal --telegram-bot-token <your-telegram-bot-token> --persist
 ```
 
-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=...
-```
+If you prefer Slack first:
 
 ```bash
-source ~/.zshrc
-# or: source ~/.bashrc
-```
-
-3. Start the service directly.
-
-```bash
-bun run start --cli codex --bootstrap personal-assistant
+clisbot start \
+  --cli codex \
+  --bot-type team \
+  --slack-app-token SLACK_APP_TOKEN \
+  --slack-bot-token SLACK_BOT_TOKEN
 ```
 
-4. Fastest first conversation path: send a direct message to the bot in Slack or Telegram.
+First conversation path:
 
-`clisbot` defaults direct messages to pairing mode. The bot will reply with a pairing code and approval command.
+- 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
 
 Approve it with:
 
 ```bash
-bun run pairing -- approve slack <CODE>
-bun run pairing -- approve telegram <CODE>
+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.
-
-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.
+Fresh config starts with no configured agents, so first-run `clisbot start` requires both `--cli` and `--bot-type` before it creates the first `default` agent.
+Fresh config also starts with no preconfigured Slack channels or Telegram groups or topics. Add those routes manually in `~/.clisbot/clisbot.json`.
+`clisbot start` requires explicit channel token input before it bootstraps anything. You can pass raw values, env names such as `TELEGRAM_BOT_TOKEN`, or placeholders such as `'${CUSTOM_TELEGRAM_BOT_TOKEN}'`.
+Set `CLISBOT_HOME` if you want a fully separate local config, state, tmux socket, wrapper, and workspace root, for example when running a dev instance beside your main bot.
 
 ## Setup Guide
 
@@ -177,7 +171,17 @@ 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.
+4. Optionally move stable channel secrets into env vars or canonical credential files after your first successful run.
+
+Separate dev home example:
+
+```bash
+export CLISBOT_HOME=~/.clisbot-dev
+clisbot start --cli codex --bot-type team --telegram-bot-token TELEGRAM_BOT_TOKEN
+```
+
+- `CLISBOT_HOME` changes the default config path, runtime state dir, tmux socket, local wrapper path, and default workspaces together
+- `CLISBOT_CONFIG_PATH` still works when you want to point at one exact config file manually
 
 Channel route setup is manual by design:
 
@@ -189,7 +193,7 @@ Channel route setup is manual by design:
 Example agent setup:
 
 ```bash
-clisbot start --cli codex --bootstrap personal-assistant
+clisbot start --cli codex --bot-type personal --telegram-bot-token <your-telegram-bot-token>
 ```
 
 ```bash
@@ -201,70 +205,36 @@ clisbot agents list --bindings
 Agent setup rules:
 
 - `agents add` requires `--cli` and currently supports `codex` and `claude`.
-- `--bootstrap` accepts `personal-assistant` or `team-assistant` and seeds the workspace from `templates/openclaw` plus the selected customized template.
+- `--bootstrap` accepts `personal-assistant` or `team-assistant` and seeds the workspace from `templates/openclaw`, `templates/customized/default`, and 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:
+Env-backed setup is still supported when you want config to reference an env name instead of persisting a credential file:
 
 ```bash
 clisbot start \
   --cli codex \
-  --bootstrap personal-assistant \
+  --bot-type personal \
   --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
+- these flags are written into `~/.clisbot/clisbot.json` as `${ENV_NAME}` placeholders
 - 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
-```
+- use this path when your environment variable names differ from `SLACK_APP_TOKEN`, `SLACK_BOT_TOKEN`, or `TELEGRAM_BOT_TOKEN`
+- keep env export details in [docs/user-guide/channel-accounts.md](docs/user-guide/channel-accounts.md) instead of front-loading them into quick start
 
 ## 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 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 bot type 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 `clisbot start` says no agents are configured, prefer `clisbot start --cli codex --bot-type personal --telegram-bot-token <your-telegram-bot-token>`.
+- If you want later runs to work with plain `clisbot start`, rerun your successful first-run command with `--persist`.
+- If `clisbot start` prints token refs as `missing`, either pass the token explicitly on the command line or switch to env-backed setup described in [docs/user-guide/channel-accounts.md](docs/user-guide/channel-accounts.md).
 - 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.
@@ -307,7 +277,7 @@ trust_level = "trusted"
 - `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 start --cli codex --bot-type personal --telegram-bot-token <your-telegram-bot-token> --persist`
 - `clisbot agents bootstrap default --mode personal-assistant`
 - `clisbot agents bind --agent default --bind telegram`
 - `clisbot agents bindings`