# botmux
Drive your AI coding CLI from Lark (Feishu). One message starts a session, each session runs its own isolated CLI process, streamed back in real time β synced across phone, desktop, and terminal.
π Docs Β·
π Quickstart Β·
β¨ Showcase Β·
δΈζ
---
A daemon watches Lark messages and spawns an isolated session process for each new session, streaming the AI coding CLI / agent's output back as live Lark cards and offering an interactive web terminal. It **doesn't reimplement agent capabilities** β it bridges the tools you already use directly (**20+ CLI / agent adapters**, see [Supported CLIs & Agents](#supported-clis--agents)).
## What it solves
- **The agent can't reach you, and you can't drive it from your phone** β the CLI runs on a dev box, you're on your phone. botmux pushes every turn as a Lark card so you can view / follow up / interrupt anywhere, and open a writable web terminal to operate it directly.
- **The CLI is blind to your Lark context** β pull a bot into a topic group / on-call group and one @ runs it right in your local repo; a session can be moved to another group with `/relay`, keeping its full context.
- **A single agent isn't enough** β put several bots backed by different CLIs in one group, @ whoever should act, and have Claude Code and Codex review the same MR β each analyzing independently and pushing back when they disagree.
## 5-Minute Setup
> About 5 minutes: a single Lark QR scan in `botmux setup` creates the app, configures all permissions, and publishes a version in one flow (add `--no-open-platform-auto` to only create the app and skip the permission + publish automation, which you then complete manually; creating the app manually / pasting credentials is a separate option inside setup).
```bash
npm install -g botmux # requires Node >= 22
botmux setup # one scan to create the app β pick a CLI β pick a working dir (permissions + publish auto-configured)
botmux start # start the daemon (botmux autostart enable for auto-start on boot)
```
Then DM the bot, or run `botmux dashboard` to create a group, and start chatting. Full steps (Lark international, manual permission / publish setup after `--no-open-platform-auto`, troubleshooting) are in the **[5-Minute Quickstart](https://deepcoldy.github.io/botmux/en/quickstart)**.
## Core Scenarios
- **[Live streaming cards](https://deepcoldy.github.io/botmux/en/cards)** β one live-updating card per turn, relaying the terminal screen verbatim as a screenshot; one tap to show/hide output, scroll, or restart/close/adopt the session.
- **[Multi-bot collaboration](https://deepcoldy.github.io/botmux/en/multi-bot)** β multi-bot @mention routing in one group; different CLIs mean different models and natural diversity β have them critique each other on design reviews, code reviews, tech-stack choices.
- **[Multi-topic orchestration](https://deepcoldy.github.io/botmux/en/multi-topic)** β hand an orchestrator a big task and it seeds topics in the group, spins up an isolated session per bot to run a pipeline, and the Lark task board shows every subtask's progress at a glance.
- **[Interactive web terminal](https://deepcoldy.github.io/botmux/en/web-terminal)** β not just viewing output: drive the CLI directly from a browser / phone, with a floating shortcut bar on mobile (Esc, Ctrl+C, arrow keys).
- **[Adopt & relay sessions](https://deepcoldy.github.io/botmux/en/adopt)** β running halfway in local tmux, `/adopt` it from your phone; `/relay` moves the whole session (same process, same memory) into a team group to continue.
- **[Scheduled tasks](https://deepcoldy.github.io/botmux/en/schedule) & [external triggers](https://deepcoldy.github.io/botmux/en/webhook)** β configure recurring tasks in natural language (alert analysis / group summaries); trigger programmatically from external systems via [Webhook](https://deepcoldy.github.io/botmux/en/webhook) or the [task-trigger API](https://deepcoldy.github.io/botmux/en/api-task-trigger).
- **[On-call mode](https://deepcoldy.github.io/botmux/en/oncall) & [voice summary](https://deepcoldy.github.io/botmux/en/voice)** β pull it into an on-call group and any member's @ triggers a probe in the project dir; once TTS is configured, each card footer gains a π voice-summary button that makes the model "speak plainly".
More: [Roles & teams](https://deepcoldy.github.io/botmux/en/roles) Β· [File sandbox](https://deepcoldy.github.io/botmux/en/sandbox) Β· [Dashboard](https://deepcoldy.github.io/botmux/en/dashboard) Β· [tmux persistence](https://deepcoldy.github.io/botmux/en/tmux) Β· [VC meeting agent (showcase)](https://bytedance.larkoffice.com/wiki/UBOXwH01CixfxfkqxUpcKgvQnsg).
## Supported CLIs & Agents
Switch with `cliId` in `bots.json`. **20+ adapters**, spanning local CLIs (process-isolated, reachable via `tmux attach`) and API / cloud agents (e.g. Mira, riff β reached over API / remote, not a local process). Representative ones:
`claude-code` Β· `codex` Β· `gemini` Β· `cursor` Β· `opencode` Β· `antigravity` Β· `copilot` Β· `grok` Β· `kimi` Β· `kiro-cli` Β· `aiden` Β· `coco` (TRAE) Β· `hermes` Β· `mira` Β· `riff` (cloud agent) β¦
The current full set of `cliId`s is authoritative in [`src/adapters/cli/registry.ts`](https://github.com/deepcoldy/botmux/blob/master/src/adapters/cli/registry.ts); per-CLI config and wrapper / gateway setups are in [CLI Adapters](https://deepcoldy.github.io/botmux/en/adapters).
## Design Philosophy: Bridge the CLI Directly, No SDK Wrapper
botmux doesn't reimplement memory, context management, tool calls, or permission systems β **most native CLI capabilities don't need reimplementing, and CLI upgrades usually benefit botmux directly** (when interfaces / params / output formats / resume semantics change, an adapter may still need to catch up). You keep talking in plain language; the daemon wraps context into structured prompts behind the scenes before feeding the CLI. An Agent-SDK-based approach is the inverse: capabilities depend on what the SDK exposes and on your own integration.
The table below compares only **verifiable integration boundaries** β it does not claim what other approaches "necessarily lack":
| Integration boundary | botmux | Agent-SDK-based approach |
|------|--------|--------------------------|
| What's bridged | The full CLI process (its built-in hooks / memory / plan mode / MCP / `/` commands) | Whatever the SDK exposes |
| CLI upgrades | Mostly benefit directly; adapter catches up when interfaces / resume change | Depends on SDK version and integration |
| Memory / context | Reuses the CLI's built-in | Depends on the SDK / self-built |
| Multi-CLI / agent | 20+ adapters, switch in one line | Depends on SDK coverage |
| Multi-bot | Multi-bot @mention routing in one group | Depends on the implementation |
| Direct terminal | Local CLIs can `tmux attach` into the real process | Depends on the implementation |
## Docs Β· Community Β· Contributing
- π **Full docs** (commands / config / best practices / troubleshooting): ****
- β¨ **Showcase** (illustrated + video): [*Create a really useful Feishu assistant in 5 minutes*](https://bytedance.larkoffice.com/wiki/UBOXwH01CixfxfkqxUpcKgvQnsg)
- β **FAQ / troubleshooting**: [FAQ](https://deepcoldy.github.io/botmux/en/faq) Β· [Common Pitfalls](https://deepcoldy.github.io/botmux/en/pitfalls)
- π¬ **Community**: the [About & Resources](https://deepcoldy.github.io/botmux/en/about) page has QR entries to join the internal / external "Botmux" chat groups.
- π€ **Contributing**: issues / PRs welcome. To add an adapter, see [CLI Adapters](https://deepcoldy.github.io/botmux/en/adapters).
- π **License**: [MIT](LICENSE)
If it's useful, drop a β Star β deepcoldy/botmux