clisbot - Agentic Coding CLI & chat bot

Want to use OpenClaw but are struggling because:

• API cost is too high, so you end up looking for LLM proxy workarounds
• you have to switch between OpenClaw for daily work and Claude / Codex for real coding
• you want to code on the go and work on the go

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 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 or Codex 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.

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 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.
• 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.
• Team-first by design, with AGENTS, USER, and MEMORY context bootstrapping shaped for shared team reality instead of only personal solo-assistant flows.
• Compatible with OpenClaw-style ideas where useful, but centered on native coding agents, team workflows, and practical operator control.
• 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.

What to expect

• You can get the first Telegram 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.
• Advanced multi-agent setup is available later, but it is not required for day one.

Quick Start

Most people should start here:

npm install -g clisbot
clisbot start \
  --cli codex \
  --bot-type personal \
  --telegram-bot-token <your-telegram-bot-token> \
  --persist

If you want to try first without persisting the token yet, just remove --persist.

What happens next:

• --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

If you prefer Slack first:

clisbot start \
  --cli codex \
  --bot-type team \
  --slack-app-token SLACK_APP_TOKEN \
  --slack-bot-token SLACK_BOT_TOKEN

Short alias:

clis start --cli codex --bot-type personal --telegram-bot-token <your-telegram-bot-token>

Local repo path:

bun install
bun run start --cli codex --bot-type personal --telegram-bot-token <your-telegram-bot-token> --persist

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

Approve it with:

clisbot pairing approve slack <CODE>
clisbot pairing approve telegram <CODE>

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 MY_TELEGRAM_BOT_TOKEN, or placeholders such as '${MY_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.

Gemini note:

• clisbot supports Gemini CLI as a routed runner target
• Gemini still needs its own reusable auth before routed prompts can succeed
• for headless or detached use, prefer GEMINI_API_KEY or Vertex AI credentials, or log in once directly with gemini

Showcase

Slack

Telegram

Important caution

Strong vendor investment in security and safety does not make frontier agentic CLI tools inherently safe. clisbot exposes those tools more broadly through chat and workflow surfaces, so you should treat the whole system as high-trust software and use it at your own risk.

Acknowledgements

clisbot would not exist without the ideas, momentum, and practical inspiration created by OpenClaw. Many configuration, routing, and workspace concepts here were learned from studying OpenClaw, then adapted to clisbot's own direction. Respect and thanks to the OpenClaw project and community.

Setup Guide

The easiest setup flow is still:

1. Install clisbot.
2. Run the quick start command above.
3. DM the bot and approve pairing.
4. Only move into advanced config after the first successful run.

If you want the repo-guided setup path:

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, so the agent should have enough context to walk you through setup, configuration, and troubleshooting directly inside the repo.

If you prefer to configure everything yourself:

1. Read the full config template in 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. Optionally move stable channel secrets into env vars or canonical credential files after your first successful run.

Separate dev home example:

export CLISBOT_HOME=~/.clisbot-dev
clisbot start --cli codex --bot-type team --telegram-bot-token DEV_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:

• 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

Advanced agent management:

• most users should stay on clisbot start --cli ... --bot-type ... and let first-run create the default agent
• if you need more than one agent, custom bindings, or manual workspace bootstrap flows, use the clisbot agents ... commands described in docs/user-guide/README.md
• README intentionally keeps that low-level surface out of the main onboarding path because the public first-run model is --bot-type personal|team, not internal template-mode naming
• fresh channel config still points at the default agent; if your first agent uses another id, update defaultAgentId and any route agentId values in config

Env-backed setup is still supported when you want config to reference an env name instead of persisting a credential file:

clisbot start \
  --cli codex \
  --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 as ${ENV_NAME} placeholders
• you can pass either CUSTOM_SLACK_APP_TOKEN or '${CUSTOM_SLACK_APP_TOKEN}'
• use this path when you want config to point at env variable names you chose yourself
• keep env export details in docs/user-guide/channel-accounts.md instead of front-loading them into quick start

Troubleshooting

If the quick start does not work, check these in order:

• If setup feels unclear, open Claude Code or Codex in this repo and ask it to help using the local docs.
• If config behavior is confusing, inspect config/clisbot.json.template first, then compare it with docs/user-guide/README.md.
• 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.
• 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 or bootstrap=...:not-bootstrapped, follow the advanced agent bootstrap steps in docs/user-guide/README.md.
• 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:

[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 Gemini startup says it is waiting for manual authorization, authenticate Gemini directly first or provide a headless auth path such as GEMINI_API_KEY or Vertex AI credentials; clisbot now treats that screen as a startup blocker instead of a healthy ready session.
• 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.
• 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.

Common CLI commands

Most users only need a small set of commands at first:

• clisbot start
• clisbot restart
• clisbot stop
• clisbot status
• clisbot logs
• 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

If you are running from the repo instead of the global package:

• 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
• Architecture
• Feature Tables
• Backlog
• User Guide

Roadmap

• Add more native CLIs, starting with a stronger Claude, Codex, and Gemini launch trio.
• Add more channels, starting from Slack and Telegram, then moving toward Zalo and other expansion surfaces.
• Add better workflow building blocks such as heartbeat, cron-style jobs, and stronger loop automation.
• Explore structured output, ACP, and native SDK integrations where they improve truthfulness or operator control.
• Explore more stable native messaging paths beyond tmux-pane capture over time.

Current Focus

clisbot is growing toward a broader agent runtime layer:

• more CLI tool support beyond Claude Code and Codex
• more communication channels beyond Slack and Telegram
• simple workflow building blocks such as cron jobs, heartbeat jobs, and loops
• durable agent sessions, workspaces, follow-up policy, commands, attachments, and operator controls that stay reusable across all those surfaces

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 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

Completed

• Multiple Codex and Claude sessions with streaming on/off support.
• Stale tmux session cleanup and session resume.
• OpenClaw-compatible configuration system.
• Slack channel support with streaming and attachments, smart follow mode
• 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
• 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.