{"id":49039456,"url":"https://github.com/longbkit/clisbot","last_synced_at":"2026-05-31T06:01:43.702Z","repository":{"id":349991902,"uuid":"1204822671","full_name":"longbkit/clisbot","owner":"longbkit","description":"Agentic Coding CLI \u0026 chat bot","archived":false,"fork":false,"pushed_at":"2026-05-24T11:09:30.000Z","size":24635,"stargazers_count":61,"open_issues_count":0,"forks_count":26,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-05-24T13:09:40.105Z","etag":null,"topics":["agentic-ai","ai-agents","chatbot","claude-code","cli","codex","coding-agent","gemini-cli","llm","openclaw","slack-bot","telegram-bot","tmux"],"latest_commit_sha":null,"homepage":"https://github.com/longbkit/clisbot","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/longbkit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-08T11:17:02.000Z","updated_at":"2026-05-24T12:20:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/longbkit/clisbot","commit_stats":null,"previous_names":["longbkit/muxbot","longbkit/clisbot"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/longbkit/clisbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longbkit%2Fclisbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longbkit%2Fclisbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longbkit%2Fclisbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longbkit%2Fclisbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/longbkit","download_url":"https://codeload.github.com/longbkit/clisbot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longbkit%2Fclisbot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33720897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","ai-agents","chatbot","claude-code","cli","codex","coding-agent","gemini-cli","llm","openclaw","slack-bot","telegram-bot","tmux"],"created_at":"2026-04-19T14:10:21.923Z","updated_at":"2026-05-31T06:01:43.695Z","avatar_url":"https://github.com/longbkit.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/brand/x-profile-banner-2026-04-29/images/clisbot-x-banner-v5-frontier-tagline-1500x500.png\" alt=\"clisbot banner\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"./README.md\"\u003eEnglish\u003c/a\u003e |\n  \u003ca href=\"./docs/langs/root/README.vi.md\"\u003eTiếng Việt\u003c/a\u003e |\n  \u003ca href=\"./docs/langs/root/README.zh-CN.md\"\u003e简体中文\u003c/a\u003e |\n  \u003ca href=\"./docs/langs/root/README.ko.md\"\u003e한국어\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/clisbot\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/clisbot?label=npm\u0026color=cb3837\" alt=\"npm version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/clisbot\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/clisbot?label=downloads\u0026color=22c55e\" alt=\"npm downloads per month\" /\u003e\u003c/a\u003e\n  \u003ca href=\"./LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-d4a017\" alt=\"MIT license\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/CLI-Codex%20%7C%20Claude%20%7C%20Gemini-111827\" alt=\"supported cli tools\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Channels-Slack%20%7C%20Telegram%20%7C%20Zalo-0a66c2\" alt=\"supported channels\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Runtime-tmux%20backed-16a34a\" alt=\"tmux backed runtime\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Workflow-AI--native-f59e0b\" alt=\"AI-native workflow\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Follow product updates on \u003ca href=\"https://x.com/clisbot\"\u003ex.com/clisbot\u003c/a\u003e.\n\u003c/p\u003e\n\n# clisbot - Turn your favorite coding CLI into an agentic personal assistant, workplace assistant, coding partner - on the go\nWant to use OpenClaw / Hermes Agent but are struggling because:\n\n- API cost is too high, so you end up looking for LLM proxy workarounds\n- you have to switch between OpenClaw / Hermes Agent for daily work and Claude / Codex / Gemini for real coding\n- you want to code on the go and work on the go\n\n`clisbot` is the right solution for you.\n\n`clisbot` turns native frontier agent CLIs like Claude Code, Codex, and Gemini CLI into durable chat-native bots across multiple channels. Current channels include Slack, Telegram, Zalo Bot, and Zalo Personal, with more to come. 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.\n\nIt is not just a tmux bridge with chat glued on top. `clisbot` treats chat platforms as real channel surfaces, including Slack, Telegram, Zalo Bot, and Zalo Personal today, 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.\n\n`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.\n\n## Why I Built This\n\nI’m Long Luong (Long), Co-founder \u0026 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.\n\nThe 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.\n\n`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, Zalo surfaces, and real team workflows.\n\nIf `clisbot` helps your workflow, a GitHub star is a simple way to let me know\nit is useful and help more people discover it.\n\n## Quick Start\n\n### AI-Assisted Setup\n\nIf you already use Codex, Claude Code, or Gemini CLI, open this repo in that\nCLI and paste this short prompt first:\n\n```text\nHelp me clarify and set up clisbot from this GitHub repo: https://github.com/longbkit/clisbot\n```\n\nIf you already know what you want, paste this more specific prompt instead and\nfill the placeholders:\n\n```text\nHelp me clarify and set up clisbot from this GitHub repo: https://github.com/longbkit/clisbot\n\nI want:\n- target channel: \u003cSlack|Telegram|Zalo Bot|Zalo Personal\u003e\n- coding CLI tool: \u003cCodex|Claude Code|Gemini CLI\u003e\n- usage shape: \u003cpersonal assistant|team assistant\u003e\n```\n\nFor AI agents: use the guide below to help a user install, set up, and onboard\nwith `clisbot` with as little friction as possible.\n\n1. Ask only the smallest number of clarify questions needed. In particular,\n   clarify:\n   - target channel: Slack, Telegram, Zalo Bot, or Zalo Personal\n   - coding CLI tool: Codex, Claude Code, or Gemini CLI\n   - usage shape: personal assistant or team assistant\n2. Prefer persisting credentials by default after the first successful test, so\n   later restarts can use plain `clisbot start` without retyping tokens.\n3. Read `README.md` and `docs/user-guide/README.md`, then guide the shortest\n   safe setup path. Run the right `clisbot` commands when the environment\n   allows it, and verify with status/logs.\n4. If a step must be done manually, such as creating a bot, setting up a Slack\n   app, or logging in to Zalo Personal, explain exactly what the user must do\n   and wait for them before continuing.\n5. If a technical limit prevents running a command, give the exact terminal\n   command for the user to run. If an unresolved bug blocks setup, help the user\n   report a GitHub issue or submit feedback at\n   https://docs.google.com/forms/d/e/1FAIpQLSd7L7mHOo0ea8YXFI4tGnyDIj94ESn4hbbDa5YTbcEKTVOKTA/viewform.\n\nPlatform support:\n\n- Linux and macOS are the supported host environments today.\n- If you use Windows, run `clisbot` inside WSL2 because native Windows is not supported yet; `clisbot` currently depends on `tmux` and Bash-based runtime flows.\n\n### Manual Setup\n\nMost people should start here:\n\n```bash\nnpm install -g clisbot\nclisbot start \\\n  --cli codex \\\n  --bot-type personal \\\n  --telegram-bot-token \u003cyour-telegram-bot-token\u003e \\\n  --persist\n```\n\nIf you want to try first without persisting the token yet, just remove `--persist`.\nDay-to-day rescue commands are `clisbot stop`, `clisbot restart`,\n`clisbot status`, and `clisbot logs`.\n\nNext steps:\n\n- For security, DMs default to pairing.\n- `clisbot` also has a smart autopairing path to reduce first-run friction. If\n  you send the bot a DM within the first 30 minutes, you can usually claim the\n  owner role immediately and start using it without a separate pairing round.\n\nNeed the step-by-step setup docs instead of the shortest path?\n\n- Telegram: [Telegram Bot Setup](docs/user-guide/telegram-setup.md)\n- Slack: [Slack App Setup](docs/user-guide/slack-setup.md)\n- Zalo Bot: [Zalo Bot Setup](docs/user-guide/zalo-bot-setup.md)\n- Zalo Personal: [Zalo Personal](docs/user-guide/zalo-personal.md)\n- Release history: [CHANGELOG.md](CHANGELOG.md), [release notes](docs/releases/README.md), [update guide](docs/updates/update-guide.md), [release guides](docs/updates/README.md), and [migration index](docs/migrations/index.md)\n- Slack app manifest template: [app-manifest.json](templates/slack/default/app-manifest.json)\n- Slack app manifest guide: [app-manifest-guide.md](templates/slack/default/app-manifest-guide.md)\n\nWhat happens next:\n\n- `--bot-type personal` creates one assistant for one human\n- `--bot-type team` creates one shared assistant for a team, channel, or group workflow\n- literal token input stays in memory unless you also pass `--persist`\n- `--persist` promotes the token into the canonical credential file so the next `clisbot start` can reuse it without retyping\n- fresh bootstrap only enables the channels you name explicitly\n- after the persisted first run, later restarts can use plain `clisbot start`\n\n## Page Index\n\n- [Start By Need](#start-by-need)\n- [Supported Channels](#supported-channels)\n- [Who It Is For](#who-it-is-for)\n- [How clisbot Fits](#how-clisbot-fits)\n- [Use Case Map](#use-case-map)\n- [First Setup FAQ](#first-setup-faq)\n- [Routing And Access FAQ](#routing-and-access-faq)\n- [Chat-Native Operator Experience](#chat-native-operator-experience)\n- [Runtime And Workflow FAQ](#runtime-and-workflow-faq)\n- [Troubleshooting By Symptom](#troubleshooting-by-symptom)\n- [Troubleshooting Playbooks](#troubleshooting-playbooks)\n- [Command Cheat Sheet](#command-cheat-sheet)\n- [Related Docs](#related-docs)\n\n## Start By Need\n\n| Need | Best first path | Why it fits | Read next |\n| --- | --- | --- | --- |\n| Personal coding assistant in chat | Telegram DM + `codex` | Lowest setup friction, strong routed coding behavior, durable workspace. | [Telegram Bot Setup](docs/user-guide/telegram-setup.md), [Codex CLI Guide](docs/user-guide/codex-cli.md) |\n| Team assistant in a shared room | Slack channel or Telegram group/topic + `codex` | Explicit routes, mention defaults, and sender policy make shared use safer. | [Slack App Setup](docs/user-guide/slack-setup.md), [Routes](docs/user-guide/channels.md) |\n| Claude Code from chat | Any routed surface + `claude` | Keeps Claude-native commands and skills reachable from chat. | [Claude CLI Guide](docs/user-guide/claude-cli.md), [Native CLI Commands](docs/user-guide/native-cli-commands.md) |\n| OpenClaw-style assistant with local memory | Personal or team bot + bootstrapped workspace | `AGENTS.md`, `USER.md`, `MEMORY.md`, pairing, routes, and channel-native UX map well to OpenClaw habits. | [User Guide](docs/user-guide/README.md), [Authorization And Roles](docs/user-guide/auth-and-roles.md) |\n| Hermes-agent-style background workflow | Schedule review of repeated and struggled tasks to create and improve skills. | One chat surface can turn hard recurring work into reusable skills, review loops, and recurring briefs. | [Slash Commands](docs/user-guide/slash-commands.md), [Runtime Operations](docs/user-guide/runtime-operations.md) |\n| Operator rescue and inspection | `clisbot status`, `logs`, `watch`, `runner inspect` | Shows channel health, runtime pid, active runs, and live runner panes. | [Runtime Operations](docs/user-guide/runtime-operations.md), [CLI Commands](docs/user-guide/cli-commands.md) |\n| Zalo automation | Zalo Bot or Zalo Personal | Zalo Bot is official-DM oriented; Zalo Personal supports local personal-account DM and group workflows while staying silent until users or groups are allowlisted. | [Zalo Bot Setup](docs/user-guide/zalo-bot-setup.md), [Zalo Personal](docs/user-guide/zalo-personal.md) |\n\n## Supported Channels\n\nCurrent user-facing channel guides:\n\n- [Slack App Setup](docs/user-guide/slack-setup.md)\n- [Telegram Bot Setup](docs/user-guide/telegram-setup.md)\n- [Zalo Bot Setup](docs/user-guide/zalo-bot-setup.md)\n- [Zalo Personal](docs/user-guide/zalo-personal.md)\n\n| Channel | Best fit | Supported surfaces | Routing shape | Status |\n| --- | --- | --- | --- | --- |\n| Slack | Team channels, private groups, workplace assistant flows. | DM, public/private channel, thread continuity. | `dm:\u003cuserId\u003e`, `group:\u003cchannelId\u003e`, `group:*` | Stable primary channel |\n| Telegram | Personal bot, mobile coding, groups, topic-isolated team workflows. | DM, group, forum topic. | `dm:\u003cuserId\u003e`, `group:\u003cchatId\u003e`, `topic:\u003cchatId\u003e:\u003ctopicId\u003e` | Stable primary channel |\n| Zalo Bot | Official Zalo bot DM flows and Vietnam-market experiments. | DM-focused today. | `dm:\u003cuser-id\u003e`, `dm:*` | Alpha; polling-first |\n| Zalo Personal | Local personal-account automation. | DM and group, silent by default until users or groups are allowlisted. | `dm:\u003cuser-id\u003e`, `dm:*`, `group:\u003cgroup-id\u003e` | Supported local channel |\n\nSimple capability map:\n\n| Capability | Slack | Telegram | Zalo Bot | Zalo Personal |\n| --- | --- | --- | --- | --- |\n| Direct messages | Yes | Yes | Yes | Yes |\n| Shared rooms | Channels and groups | Groups | No current group model | Groups |\n| Child conversation isolation | Threads | Forum topics | No | No topic/thread model |\n| Pairing / first access flow | Yes | Yes | Yes | Opt-in; default silent |\n| Route allowlists | Yes | Yes | DM allowlists | DM and group allowlists |\n| Chat-native queue/loop use | Yes | Yes | Yes, DM-oriented | Yes, route-scoped |\n| Message send CLI | Yes | Yes | Yes, text and URL-backed photo path | Yes, text and file/URL media path |\n| Inbound attachments | Supported through routed attachments | Supported through routed attachments | Images/stickers to `.attachments/` | Images and grouped image handling |\n| Best default runner | `codex` | `codex` | `codex` | `codex` |\n\nUse the channel guide that matches the target surface. Slack and Telegram are\nthe most stable public user experience today; Zalo Bot and Zalo Personal are\nthe right fit when the target market or test surface specifically needs Zalo,\nwith the safety notes in the channel guide close at hand.\n\n## Who It Is For\n\n| Audience | Common goal | Recommended shape | Main risk to manage |\n| --- | --- | --- | --- |\n| Solo builder | Code from phone or chat without losing a real repo workspace. | `--bot-type personal`, Telegram DM, `codex`. | Native CLI auth or missing host dependencies. |\n| Office worker | Use a frontier agent for business work, marketing, research, writing, planning, reporting, and follow-up without living in a terminal or separate AI app. | `--bot-type personal`, the channel you already use most, `codex` or your preferred CLI. | Giving the bot too broad a workspace before you have clear habits and permissions. |\n| Team member | Bring an assistant into the work channel where decisions, files, and follow-ups already happen. | `--bot-type team`, shared room route, mention required, queue/loop for follow-up. | Confusing a shared assistant with a private assistant; route and sender policy should be explicit. |\n| Business, marketing, or operations team | Turn recurring reports, campaign briefs, customer or market research, document updates, reviews, reminders, and cross-functional requests into chat-native workflows. | Slack, Telegram, Zalo Bot, or Zalo Personal depending on the team's real channel; queues and loops for repeated work. | Scheduling with the wrong timezone, sender identity, or target channel. |\n| Engineering lead | Put an assistant in a team channel without opening it to everyone. | `--bot-type team`, shared route allowlist, mention required. | Route admission and sender policy confusion. |\n| AI workflow operator | Run repeated reviews, status checks, and follow-up work. | Chat-native requests backed by `/queue`, `/loop`, `clisbot queues`, and `clisbot loops`. | Loops or queues created with the wrong sender, target, or timezone. |\n| Claude-heavy team | Keep existing Claude Code command and skill habits. | `claude` runner, native command pass-through, streaming on for long tasks. | Claude plan approval and auto-mode behavior may still appear. |\n| OpenClaw / Hermes Agent user | Keep channel-native assistant ergonomics, memory, background work, and skill evolution while using frontier coding CLIs. | Routed chat surfaces, memory files, workspace bootstrap, scheduled skill review loops. | Assuming every OpenClaw or Hermes behavior maps one-to-one. |\n| Platform builder | Evaluate clisbot as a local agent runtime layer. | Multiple agents, explicit routes, runtime inspection, queue/loop primitives. | Blurring channel, control, agents, and runner ownership. |\n\n## How clisbot Fits\n\n`clisbot` turns native CLI agents such as Codex, Claude Code, and Gemini CLI\ninto durable Slack, Telegram, and Zalo-accessible bots. Each agent runs in a\nreal workspace through a tmux-backed runner, while channels own chat-native\npresentation, routing, pairing, file handling, and follow-up behavior.\n\nThe main problem it solves is not just \"send terminal text to chat.\" It gives\noperators a safer way to expose expensive, subscription-backed coding agents to\nreal communication surfaces without rebuilding every workflow around an API-only\nassistant product.\n\nKey fit:\n\n- Use Codex when you want the safest default for routed coding work.\n- Use Claude when Claude Code itself is the priority and you accept more\n  operator supervision on long tasks.\n- Use Gemini when Gemini auth is already clean and you specifically want Gemini.\n- Use clisbot as a lower-cost replacement for most OpenClaw-style assistant\n  workflows when the goal is memory, workspace continuity, pairing,\n  channel-native UX, and routed chat access to powerful agents.\n- Use clisbot for Hermes-agent-style background workflow when you want durable\n  queue and loop primitives plus skill creation and skill improvement inside a\n  real coding-agent workspace.\n- Use chat-native operation first: ask the bot to create loops, add routes,\n  update clisbot, summarize release changes, or inspect its own runtime. Slash\n  commands and CLI commands are still available as explicit control surfaces and\n  reliable fallbacks.\n\n## Use Case Map\n\n| Use case | Typical prompt | Useful controls | Notes |\n| --- | --- | --- | --- |\n| Quick coding task | \"Fix the failing test and send me the diff.\" | `/streaming on`, `/watch every 30s`, `/stop` | Start with Codex unless another CLI is required. |\n| Code review loop | \"After this implementation, queue a code review against architecture and fix the issues.\" | Bot-created queue, `/queue`, `clisbot queues list` | Queue keeps steps sequential instead of steering the current run. |\n| Team group assistant | \"@bot summarize this incident thread\" | `routes add`, `routes add-allow-user`, `/mention` | Keep mention required in shared groups by default. |\n| Recurring operations brief | \"Create a weekday 09:00 loop that checks CI and summarizes risk.\" | Bot-created loop, `/loop status`, `/loop cancel \u003cid\u003e` | Verify timezone in the creation response. |\n| Native Claude skill | \"`/code-review`\" | Native command pass-through | In Slack, send a leading space if Slack intercepts `/...`. |\n| Personal memory assistant | \"Remember this project rule and update the workspace docs.\" | Bootstrapped `AGENTS.md`, `USER.md`, `MEMORY.md` | Keep private memory out of shared contexts. |\n| Mobile coding companion | \"Continue the repo task from my phone.\" | `/attach`, `/detach`, `/watch`, `/new` | The workspace stays on the machine; chat is the control surface. |\n| Bot self-update | \"Update clisbot, follow the update guide, then summarize what changed.\" | Bot checks `clisbot update --help`, operator auth, `clisbot status` | The bot can perform the routine update path when it has permission. |\n| Zalo local automation | \"Allow this Zalo user or group to use the work bot.\" | `dm:*` allowUsers or exact `group:\u003cid\u003e` routes | Keep Zalo Personal silent except for intentionally allowlisted users or groups. |\n\n## First Setup FAQ\n\n### Which CLI should I choose first?\n\nChoose `codex` for the safest general routed coding experience. It currently\nhas the strongest default operator stability in clisbot.\n\nChoose `claude` when your team already depends on Claude Code, Claude-native\ncommands, or Claude-specific skills. Turn streaming on for longer tasks so you\ncan see if Claude is waiting at a plan approval step.\n\nChoose `gemini` when Gemini is already authenticated in the runtime environment\nand you specifically want Gemini. If Gemini opens OAuth or setup screens, fix\nGemini auth directly first.\n\nRelated pages: [Codex CLI Guide](docs/user-guide/codex-cli.md), [Claude CLI Guide](docs/user-guide/claude-cli.md),\n[Gemini CLI Guide](docs/user-guide/gemini-cli.md).\n\n### Should I start with Telegram or Slack?\n\nUse Telegram when you want the simplest personal bot path. Use Slack when the\nworkflow is team-channel first. Telegram topics and Slack threads both work well\nas isolated conversation surfaces once routes are explicit.\n\nRelated pages: [Telegram Bot Setup](docs/user-guide/telegram-setup.md), [Slack App Setup](docs/user-guide/slack-setup.md).\n\n### What is the difference between personal and team bot type?\n\n`--bot-type personal` creates a default assistant shaped for one human. It is a\ngood default for Telegram DM or a private assistant.\n\n`--bot-type team` creates a shared assistant shape for a team, group, channel, or\ntopic workflow. It is a good default for Slack channel use.\n\n### Why does the first run require both `--cli` and `--bot-type`?\n\nA fresh config starts with no agents. `--cli` chooses the runner family, and\n`--bot-type` chooses the workspace/bootstrap shape for the first `default`\nagent.\n\nExample:\n\n```bash\nclisbot start --cli codex --bot-type personal --telegram-bot-token \u003ctoken\u003e --persist\n```\n\n### Is clisbot an OpenClaw replacement?\n\nFor most OpenClaw-style workflows, yes. clisbot is intended to be a better\nreplacement when you want the same assistant shape: memory, workspace\ncontinuity, pairing, channel-native routing, and chat access from Slack,\nTelegram, or Zalo.\n\nThe main difference is the execution model. OpenClaw-style systems usually point\nyou toward API-backed agents. clisbot runs frontier coding CLIs such as Codex,\nClaude Code, and Gemini CLI as durable agents behind chat surfaces. That can be\nmuch cheaper for many users because it reuses the CLI subscriptions they already\npay for instead of forcing every useful workflow through API-metered usage.\n\nIt is also stronger for coding-native work. The same bot can act as a daily\nassistant, workplace assistant, and team assistant, but when the task becomes\n\"edit the repo, run tests, improve docs, create a skill, or fix the workflow,\"\nit is already sitting inside the native coding-agent environment where those\ntasks are strongest.\n\n### Is clisbot a Hermes agent?\n\nIt can cover most Hermes-agent-style use cases, but it reaches them through\ndurable coding agents instead of a separate agent product boundary.\n\nHermes-style self-evolution maps naturally to clisbot because an agent can keep\nworking in a real workspace, use `/queue` for sequential follow-up, use `/loop`\nfor daily or weekly review, and update its own operating files, docs, tools, or\nskills after hard tasks. If a task exposes a repeated weakness, you can ask the\nagent to create a new skill or improve an existing one, then reuse that skill in\nfuture work. Daily and weekly loops can do the same thing as a deliberate\nmaintenance rhythm.\n\nThe practical positioning is: clisbot is both an assistant and a native coding\nagent surface. It can handle general office-worker workflows through chat,\nfiles, memory, and tools, while still being unusually strong when the work\nrequires code, repo edits, tests, automation scripts, or skill evolution.\n\n## Routing And Access FAQ\n\n### Why does the bot answer in DM but not in a group?\n\nDMs and shared surfaces are gated separately. Fresh configs do not automatically\nadmit Slack channels, Telegram groups, Telegram topics, or Zalo Personal groups.\nAdd an explicit route:\n\n```bash\nclisbot routes add --channel telegram group:\u003cchatId\u003e --bot default\nclisbot routes add --channel telegram topic:\u003cchatId\u003e:\u003ctopicId\u003e --bot default\nclisbot routes add --channel slack group:\u003cchannelId\u003e --bot default\n```\n\nUse `/whoami` in the target surface to discover ids where supported.\n\n### What does `group:*` mean?\n\n`group:*` is the default multi-user sender policy node under one bot. It is not\nthe same thing as admitting every group. Exact shared routes still decide which\ngroups, topics, or channels are admitted when the bot's shared admission policy\nis `allowlist`.\n\n### Why does the deny message say \"group\" in Slack channels or Telegram topics?\n\nThe deny text intentionally uses one common human-facing word for multi-user\nsurfaces. Internally, provider-specific surfaces still map to canonical route\nconcepts such as `group` and `topic`.\n\n### Why does the bot require a mention in groups?\n\nShared surfaces default toward safer behavior. Mention-required routes reduce\naccidental bot activation in busy rooms. Use `/mention`, `/mention channel`, or\n`/mention all` to tighten mention behavior, or `routes set-require-mention` when\nyou intentionally want a route to listen without mention.\n\n### How do I let only selected people use the bot in a shared surface?\n\nAdd the route, keep or set its policy to `allowlist`, then add allowed users:\n\n```bash\nclisbot routes add --channel telegram group:\u003cchatId\u003e --bot default --policy allowlist\nclisbot routes add-allow-user --channel telegram group:\u003cchatId\u003e --bot default --user \u003cuserId\u003e\n```\n\nSurface policy decides who may reach the bot. Auth roles decide what they may do\nafter they get in.\n\nRelated page: [Authorization And Roles](docs/user-guide/auth-and-roles.md).\n\n## Chat-Native Operator Experience\n\n### Do I need to memorize slash commands and CLI commands?\n\nNo. The preferred product experience is chat-native: ask the bot what you want,\nand let it inspect the relevant help, run the right `clisbot` command, and\nreport the result.\n\nGood prompts:\n\n```text\nCreate a loop every weekday at 09:00 that checks CI and summarizes risk here.\nQueue a code review after the current implementation finishes, then run tests.\nAdd this Telegram topic to the default bot if I am allowed to manage routes.\nUpdate clisbot, follow the update guide, restart safely, and summarize what changed.\n```\n\nSlash commands such as `/loop`, `/queue`, `/watch`, and `/status` still matter.\nThey are the precise chat control surface for users who already know the command\nthey want. The CLI remains the explicit operator surface and fallback when you\nneed exact, scriptable control.\n\n### How does bot-native configuration stay safe?\n\nclisbot is designed so the bot can help configure itself without treating every\nchat message as permission to mutate protected state.\n\nThe important guardrails are:\n\n- surface routes decide where the bot may answer at all\n- auth roles and permissions decide whether a sender may manage routes, queues,\n  loops, runtime operations, or protected resources\n- the agent prompt tells the bot to use `clisbot` CLI help for configuration,\n  update, loop, queue, and route requests instead of inventing commands\n- sensitive actions should be preceded by a read-only permission check such as\n  `clisbot auth get-permissions --sender \u003cprincipal\u003e --agent \u003cagentId\u003e --json`\n- runtime monitoring, `status`, `logs`, `watch`, `/attach`, `/stop`, and\n  `stop --hard` give operators recovery paths if a native CLI or runner gets\n  stuck\n\nThat is the intended balance: you can operate clisbot by chatting with it, while\nconfiguration changes still pass through explicit command surfaces, auth checks,\ndurable state, and observable recovery mechanisms.\n\n## Runtime And Workflow FAQ\n\n### What should I use when a run is taking a long time?\n\nUse `/attach` to resume live updates in the current thread. Use\n`/watch every 30s` for periodic updates. Use `/detach` when you want the run to\ncontinue quietly and still post the final result.\n\nUse `/stop` only when you want to interrupt the current run.\n\n### What is the difference between queue and steer?\n\n`/queue \u003cmessage\u003e` stores a prompt behind the current run and executes it later\nin order. Use it for review-after-code, test-after-fix, or deliberate\nmulti-step work.\n\n`/steer \u003cmessage\u003e` injects a prompt into the active run now. Use it when the\ncurrent run is going in the wrong direction and must be corrected immediately.\n\n### When should I create a loop?\n\nUse loops for repeated or scheduled work. The easiest path is to ask the bot to\ncreate the loop in plain language:\n\n```text\nCreate a loop every weekday at 09:00 that summarizes open operational risks here.\nRun this review prompt 3 times, one after another, until the issues are fixed.\nCheck CI every 2 hours and summarize only actionable failures.\n```\n\nThe bot should inspect the live loop help when needed, create the loop through\nthe clisbot control surface, and report the resolved timezone and cancel\ncommand. Direct `/loop ...` commands still work when you want exact syntax.\n\nLoops are durable and session-scoped. Check loop state by asking the bot, with\n`/loop status`, or with `clisbot loops status`. Cancel stale loops before\ncreating replacements.\n\n### Why did a queued or looped prompt not run immediately?\n\nManaged loops are skip-if-busy, and queues wait for the current logical run to\nsettle. This avoids corrupting the active conversation or piling unrelated\nprompts into one run.\n\n### How do native CLI commands work?\n\nclisbot reserves a small set of control commands such as `/status`, `/stop`,\n`/queue`, and `/loop`. Other slash commands are forwarded unchanged to the\nunderlying CLI. That is why Claude-native commands like `/code-review` and\nCodex-native habits such as `/review` or `$code-review` can still work.\n\nRelated page: [Native CLI Commands](docs/user-guide/native-cli-commands.md).\n\n## Troubleshooting By Symptom\n\n| Symptom | First check | Likely cause | Fix |\n| --- | --- | --- | --- |\n| `clisbot start` says no agents are configured | `clisbot start --help` | Fresh config has no agent yet. | Start with both `--cli` and `--bot-type`. |\n| Token refs show `missing` | `clisbot status` | Env var is not visible to the runtime. | Pass token again, persist it, or restart from a shell with the env exported. |\n| Channel stays `starting` | `clisbot logs` | Credential, network, auth, or provider startup failure. | Fix the provider error shown in logs, then restart. |\n| Bot answers in DM but not group | `/whoami` in group/topic | Missing shared route or mention requirement. | Add `group:\u003cid\u003e` or `topic:\u003cchatId\u003e:\u003ctopicId\u003e` route. |\n| Message accepted but no answer arrives | `clisbot watch --latest --lines 100` | Runner is blocked, unauthenticated, or waiting at a prompt. | Fix the native CLI state in the workspace, then restart or `/new`. |\n| Native CLI runner does not answer | `codex`, `claude`, or `gemini` directly in terminal | The underlying coding CLI is not installed, authenticated, trusted, or able to run on this machine. | Fix the native CLI first; clisbot only works after the CLI can answer normally. |\n| Channel or runtime feels stuck | `clisbot status` and `clisbot logs` | Channel worker, detached runtime, or tmux runner state is stale. | Try `clisbot restart`; if that is not enough, run `clisbot stop --hard` then `clisbot start`. |\n| Claude appears stuck | `/streaming on` and `/watch every 30s` | Claude plan approval or auto-mode behavior. | Send `/nudge` if it is waiting for default confirmation. |\n| Gemini startup blocks | `clisbot logs` | Gemini OAuth or setup screen. | Authenticate Gemini directly or provide a headless auth path. |\n| Codex reports missing env var | `clisbot watch --latest` | Detached runtime did not inherit your shell env. | Restart clisbot from a shell with the env, or configure the service env. |\n| Slack slash command does not reach clisbot | Slack client behavior | Slack intercepts leading `/...`. | Send a leading space, for example ` /status`, or use `\\status`. |\n| Old behavior survives restart | `clisbot runner list` | Stale tmux runner or old environment. | Use `clisbot stop --hard`, then start again. |\n| Update or restart seems stuck | `clisbot status` | Worker already exited or monitor is in transition. | Check status first; then run `clisbot start` if runtime is down. |\n\n## Troubleshooting Playbooks\n\n### Check The Native CLI First\n\nWhen clisbot accepts a message but the agent does not answer, first separate\nclisbot from the underlying coding CLI.\n\n1. Open a terminal on the same machine.\n2. Go to the workspace you expect clisbot to use, usually\n   `~/.clisbot/workspaces/default`.\n3. Start the configured CLI directly:\n\n```bash\ncodex\nclaude\ngemini\n```\n\n4. Say `hi` and confirm the CLI can answer.\n5. If the CLI cannot start or reply, fix its install, login, trust prompt,\n   model access, or local dependency issue first. clisbot cannot make a broken\n   native CLI work; it can only run and route a CLI that already works on the\n   machine.\n\n### Reset A Stuck Channel Or Runtime\n\nIf the native CLI works in terminal but the chat channel is still stuck, reset\nthe clisbot runtime boundary.\n\n1. Try the normal restart first:\n\n```bash\nclisbot restart\n```\n\n2. If stale tmux sessions or old channel state still survive, hard-stop all\n   clisbot tmux sessions and start fresh:\n\n```bash\nclisbot stop --hard\nclisbot start\n```\n\n3. After the restart, run `clisbot status` and send one small test message from\n   the target channel.\n\n### Bot Does Not Start\n\n1. Run `clisbot status`.\n2. Run `clisbot logs`.\n3. Confirm token refs are present and the channel is enabled.\n4. If this is the first run, include both `--cli` and `--bot-type`.\n5. If a normal restart is not enough, run `clisbot stop --hard`, then start\n   again from a shell with the correct environment.\n\n### Bot Does Not Reply In A Routed Surface\n\n1. Send `/whoami` in the surface.\n2. Confirm the exact route exists with `clisbot routes list --channel \u003cchannel\u003e`.\n3. Confirm sender policy does not block the user.\n4. Confirm the message mentions the bot when `requireMention` is true.\n5. Run `clisbot watch --latest --lines 100` after one test message to inspect\n   the runner pane.\n\n### Runner Looks Stuck\n\n1. Run `clisbot runner list`.\n2. Run `clisbot runner inspect --latest`.\n3. Use `clisbot watch --latest --lines 100` to see the live pane.\n4. Open the workspace directly, usually `~/.clisbot/workspaces/default`.\n5. Start the native CLI there and clear auth, trust, or dependency prompts.\n6. Use `/nudge`, `/stop`, or `/new` depending on whether the run is waiting,\n   wrong, or needs a fresh conversation.\n\n### Access Control Is Confusing\n\n1. Separate the two questions:\n   - route policy: may this sender reach this surface?\n   - auth role: what may this sender do after admission?\n2. Use `clisbot routes get --channel \u003cchannel\u003e \u003croute-id\u003e --bot \u003cbot\u003e`.\n3. Use:\n\n```bash\nclisbot auth get-permissions --sender \u003cprincipal\u003e --agent \u003cagentId\u003e --json\n```\n\n4. Remember that `disabled` wins over owner/admin, and `blockUsers` still wins.\n\n### Queue Or Loop Behavior Is Surprising\n\n1. Check the current session with `/status`.\n2. List pending queue items with `/queue list` or `clisbot queues list`.\n3. Check loops with `/loop status` or `clisbot loops status`.\n4. Confirm the loop timezone in the creation response.\n5. Cancel stale loops before creating replacement schedules.\n\n## Command Cheat Sheet\n\n| Job | Command |\n| --- | --- |\n| Start first Telegram personal bot | `clisbot start --cli codex --bot-type personal --telegram-bot-token \u003ctoken\u003e --persist` |\n| Start first Slack team bot | `clisbot start --cli codex --bot-type team --slack-app-token \u003cxapp\u003e --slack-bot-token \u003cxoxb\u003e --persist` |\n| Check runtime health | `clisbot status` |\n| Read recent logs | `clisbot logs` |\n| Inspect live runner output | `clisbot watch --latest --lines 100` |\n| Add Telegram group route | `clisbot routes add --channel telegram group:\u003cchatId\u003e --bot default` |\n| Add Telegram topic route | `clisbot routes add --channel telegram topic:\u003cchatId\u003e:\u003ctopicId\u003e --bot default` |\n| Add Slack channel route | `clisbot routes add --channel slack group:\u003cchannelId\u003e --bot default` |\n| Approve DM pairing | `clisbot pairing approve \u003cchannel\u003e \u003ccode\u003e` |\n| Hard reset runtime sessions | `clisbot stop --hard` |\n| Show update instructions | `clisbot update --help` |\n\n## Related Docs\n\n- [User Guide](docs/user-guide/README.md)\n- [CLI Commands](docs/user-guide/cli-commands.md)\n- [Runtime Operations](docs/user-guide/runtime-operations.md)\n- [Routes](docs/user-guide/channels.md)\n- [Surface Access Model](docs/user-guide/surface-access-model.md)\n- [Bots And Credentials](docs/user-guide/bots-and-credentials.md)\n- [Authorization And Roles](docs/user-guide/auth-and-roles.md)\n- [Slash Commands](docs/user-guide/slash-commands.md)\n- [Agent Progress Replies](docs/user-guide/agent-progress-replies.md)\n- [Telegram Bot Setup](docs/user-guide/telegram-setup.md)\n- [Slack App Setup](docs/user-guide/slack-setup.md)\n- [Zalo Bot Setup](docs/user-guide/zalo-bot-setup.md)\n- [Zalo Personal](docs/user-guide/zalo-personal.md)\n\n\n## CLI Compatibility Snapshot\n\n`clisbot` currently works well with Codex, Claude, and Gemini.\n\n| CLI      | Current Stability   | Short Take                                                                                                  |\n| ----------| ---------------------| -------------------------------------------------------------------------------------------------------------|\n| `codex`  | Best today          | Strongest default for routed coding work.                                                                   |\n| `claude` | Usable with caveats | Claude can surface its own plan-approval and auto-mode behavior even when launched with bypass-permissions. |\n| `gemini` | Fully compatible   | Gemini is supported as a first-class runner for routed chat-native workflows.                               |\n\nCLI-specific operator notes:\n\n- [Codex CLI Guide](docs/user-guide/codex-cli.md)\n- [Claude CLI Guide](docs/user-guide/claude-cli.md)\n- [Gemini CLI Guide](docs/user-guide/gemini-cli.md)\n\n## Recent Release Highlights\n\n- `v0.1.53`: refreshes the main README and localized user guides, adds Zalo Bot QR onboarding and Zalo Personal media guidance, fixes queue/loop/message-tool edge cases, tightens Slack/Telegram/Zalo channel behavior, and adds admin-only sensitive channel permissions for contact, group, and channel-native actions.\n- `v0.1.52`: clarifies shared-route setup so `routes add ...` clearly means “use the agent currently assigned to that bot by default,” and prunes stale short `startupDelayMs` overrides so upgraded installs can actually inherit the newer 60-second startup default.\n- `v0.1.51`: raises the default runner startup window to 60 seconds across the\n  standard CLI families and the shared runner fallback, so slower fresh launches\n  are less likely to fail before the first prompt can be submitted.\n- `v0.1.50`: a much more AI-native operator experience, where you can\n  increasingly talk to the bot to manage itself; plus safer personal and team\n  bots in real shared chat surfaces, automatic direct updates from older\n  installs, durable queue control, clearer session continuity truth, more\n  reliable scheduled loops, stronger trust/restart behavior, and stricter\n  streaming/session isolation.\n- `v0.1.43`: more durable runtime recovery, clearer routed follow-up controls, more truthful tmux prompt submission checks, better queued-start notifications, and safer Slack thread attachment behavior.\n\nWhat the current stable line most likely means for you:\n\n- The headline is AI-native control: ask the bot in chat to queue work,\n  schedule recurring briefs, help update itself, explain release changes, or\n  guide setup and routing instead of dropping to the shell for every action.\n- personal user: fewer fragile long-run failures, better `/queue`, better media\n  handling on Telegram\n- shared bot owner: clearer route safety, easier direct upgrade from older\n  installs, and more interesting team use cases where one bot lives in the\n  group but only responds to selected people there\n- operator: better queue visibility, better session continuity truth, and\n  restart behavior that is less misleading during updates, plus faster\n  `watch` and `inspect` shortcuts when something goes wrong\n\nThere are many more useful fixes and operator improvements in the full release\nnotes, including config update safety, CLI help, setup docs, runner debugging,\nroute policy behavior, channel-specific polish, and the broader AI-native\nworkflow direction behind this release.\n\nRead the full notes here:\n\n- [CHANGELOG.md](CHANGELOG.md)\n- [Release Notes Index](docs/releases/README.md)\n- [v0.1.53 Release Notes](docs/releases/v0.1.53.md)\n- [v0.1.52 Release Notes](docs/releases/v0.1.52.md)\n- [v0.1.51 Release Notes](docs/releases/v0.1.51.md)\n- [v0.1.50 Release Notes](docs/releases/v0.1.50.md)\n- [v0.1.43 Release Notes](docs/releases/v0.1.43.md)\n- [v0.1.39 Release Notes](docs/releases/v0.1.39.md)\n\n\n## Showcase\n\nThe goal is a real chat-native agent surface, not a terminal transcript mirror: threads, topics, follow-up behavior, and file-aware workflows should feel native to each supported channel surface.\n\nSlack\n\n![Slack showcase](https://raw.githubusercontent.com/longbkit/clisbot/main/docs/pics/slack-01.jpg)\n\nTelegram\n\n![Telegram topic showcase 1](https://raw.githubusercontent.com/longbkit/clisbot/main/docs/pics/telegram-01.jpg)\n\n![Telegram topic showcase 2](https://raw.githubusercontent.com/longbkit/clisbot/main/docs/pics/telegram-02.jpg)\n\n![Telegram topic showcase 3](https://raw.githubusercontent.com/longbkit/clisbot/main/docs/pics/telegram-03.jpg)\n\n## Important caution\n\nStrong 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.\n\n## Acknowledgements\n\n`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.\n\n\n## Docs\n\n- [Localized Docs Hub](docs/langs/README.md)\n- [Vietnamese Repo README](docs/langs/root/README.vi.md)\n- [Simplified Chinese Repo README](docs/langs/root/README.zh-CN.md)\n- [Korean Repo README](docs/langs/root/README.ko.md)\n- [Overview](docs/overview/README.md)\n- [Architecture](docs/architecture/README.md)\n- [Development Guide](docs/development/README.md)\n- [Feature Tables](docs/features/feature-tables.md)\n- [Backlog](docs/tasks/backlog.md)\n- [User Guide](docs/user-guide/README.md)\n\n## Roadmap\n\nCurrent shipped foundation:\n\n- Native CLI runners: Codex, Claude Code, and Gemini CLI.\n- Channels: Telegram, Slack, Zalo Bot, and Zalo Personal.\n- Workflow primitives: durable queues and loops are stable enough for real chat-native operations work.\n\nNext focus:\n\n- Standardize auto-skill creation and improvement, similar to the Hermes agent pattern: repeated or struggled tasks should become reusable skills over daily and weekly review loops.\n- Add the next channel wave: Discord and WhatsApp Personal unofficial.\n- Keep improving runtime safety, recovery, and channel-native operator experience around the durable tmux runner boundary.\n\n## AI-Native Workflow\n\nThis repo also serves as a small example of an AI-native engineering workflow:\n\n- simple `AGENTS.md`-style operating rules, with Claude and Gemini compatibility files able to symlink back to the same source\n- lessons-learned docs to capture repeated feedback and pitfalls\n- architecture docs used as a stable implementation contract\n- end-to-end validation expectations to close the feedback loop for AI agents\n- workflow docs for shortest-review-first artifacts, repeated review loops, and task-readiness shaping in [docs/workflow/README.md](docs/workflow/README.md)\n\n## Bug Report\n\nThe preferred way to report bugs is to create an issue in this GitHub repo.\nYou can also report through this\n[Google Form](https://docs.google.com/forms/d/e/1FAIpQLSd7L7mHOo0ea8YXFI4tGnyDIj94ESn4hbbDa5YTbcEKTVOKTA/viewform).\nPlease include:\n\n- your clisbot version\n- channel and runner used\n- what you expected\n- what happened instead\n- relevant `clisbot status` or `clisbot logs` output with secrets removed\n\n## Contributing\n\nMerge requests are welcome.\n\nMRs with real tests, screenshots, or recordings of the behavior under test will be merged faster.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flongbkit%2Fclisbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flongbkit%2Fclisbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flongbkit%2Fclisbot/lists"}