botmux CLI
botmux connects Lark and Feishu to Claude Code, Codex, Gemini CLI and OpenCode: each message starts its own agent session with live cards
- 1,741 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Every chat message starts a terminal agent with access to your working directory and shell commands
- The web terminal gives write access to a live agent session from a phone or browser
- The wizard creates a Lark app, grants it permissions and publishes a version, and the daemon can start with the system
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/botmuxDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Every chat message starts a terminal agent with access to your working directory and shell commands
- The web terminal gives write access to a live agent session from a phone or browser
- The wizard creates a Lark app, grants it permissions and publishes a version, and the daemon can start with the system
This is third-party code. Review the repository files before installing.
What it does
botmux drives Claude Code, Codex, Gemini CLI, OpenCode and other terminal agents from the Lark (Feishu) messenger. A background daemon listens to the bot's messages and, for each new chat, group or topic, starts a separate process of the chosen agent in your working directory. The agent's reply comes back as a live card that updates while the work runs. The card shows the terminal screen as a screenshot, and its buttons collapse the output, scroll it, restart the session or close it. botmux attaches to the real console process with its hooks, memory and `/` commands and does not rebuild the agent's features. So the same MCP servers work as in a regular terminal. There are more than twenty adapters; the agent is set by the `cliId` field in `bots.json`, and `/cli codex` changes it for a single session. While a session runs you can reach the same process through `tmux attach` or open the web terminal, which has Esc, Ctrl+C and arrow keys for a phone. More scenarios build on that. `/adopt` pulls a session already running in local tmux into the chat, and `/relay` moves it to another group with its context. One group can hold several bots on different agents, each called by a mention, for example to review one merge request together. There are recurring tasks written in plain language, webhook triggers, an on-call group mode and a voice summary on cards when text-to-speech is configured.
Who it is for. For developers and teams who work in Lark or Feishu and want to run terminal AI agents from a phone or work groups without logging in to the machine over SSH.
Good fit when
- The agent runs on a work computer or server while you are away and want to follow progress, ask questions and interrupt it from a phone
- Your team lives in Lark or Feishu, and an incident review or code review is easier to start by mentioning the bot in an on-call group
- You want two agents, such as Claude Code and Codex, to give their views on the same merge request in one group
- A session started in a terminal and has to be handed to colleagues with `/relay` without losing context
- A recurring task, such as an alert digest, is easier to describe in plain words in a chat than to script with cron
Not a fit when
- You use Telegram, Slack or another messenger: the project has adapters for Lark and Feishu only
- You are on Windows without WSL2: the daemon needs a PTY, tmux and Unix signals, so it will not run on plain Windows
- You only want notifications and approvals for agent actions without starting sessions from chat: tlive covers that case
- You need access to the agent from a phone through native mobile apps rather than through a messenger: HAPI does that
Example request
Install botmux on this server, connect it to Claude Code and show me how to start a session from a work group in LarkLimitations
- It runs on Linux and macOS (x64 and arm64). On Windows install it inside WSL2, because the daemon needs a PTY, tmux and Unix signals.
- The bot creates the Lark app through a QR code scan and configures permissions and publishes a version by itself. The `--no-open-platform-auto` flag leaves permissions and publishing to you.
- Releases older than v3.18.0 must not be upgraded through npm: the move from Node sources to a binary build stops the daemon from restarting. Upgrade by re-running the install command.
- Zero prompt injection does not work with remote backends or with the version 3 workflow. For Cursor and Antigravity it enables a separate collection of replies from transcripts, and the `scratch` isolation does not support these two agents.
- The model proxy mode is marked experimental. Keep only non-secret settings and paths to key files in `bots.json`.
- MIT license.
How to disable. Stop the daemon with `botmux stop` and turn off autostart with `botmux autostart disable`. The binary sits in `~/.botmux/bin`: delete that directory and the PATH line the installer added to the shell startup file.
FAQ
How do I control Claude Code from Lark or Feishu?
Install botmux, run `botmux setup` and scan the QR code: the wizard creates the Lark app and lets you pick an agent, such as Claude Code, and a working directory. After `botmux start`, message the bot directly or in a group, and each message starts a separate agent session in that directory.
Does botmux need Node.js to install?
Not when you install with the `curl` command from `install.sh`: botmux ships as a single self-contained binary, its SHA-256 checksum is verified during install, and the file lands in `~/.botmux/bin`. Installing through `npm install -g botmux` needs Node 22 or newer, but it carries the same binary.
How do I take over a session that is already running in a terminal and hand it to a team?
For local tmux, `/adopt` pulls the session into the chat. `/relay` moves it to another group together with the process and memory, so context is kept.
Can Claude Code and Codex run in one group?
Yes. Add bots to the group, each configured for its own agent through `cliId`, and call the one you need with a mention. According to the project they can review the same merge request independently and push back when they disagree.
How do I run the agent on a schedule or from a webhook?
A schedule is set in plain words in the chat, for example for an alert digest. For external systems there are a webhook and a task-trigger API described in the project documentation.
Does botmux work on Windows?
Only inside WSL2. The daemon uses a PTY, tmux and Unix signals and will not start on Windows without WSL2. On an unsupported platform the installer reports an error and keeps the previous version in place.
Discussion
No questions or reviews yet.
Related
CLI toolsA CLI that lets agents in different terminals message, watch and spawn each other
A skill for messaging between Claude Code, Codex, Gemini CLI and other CLI agents through a shared local SQLite database, written in bash
Ten AI agents in tmux panes: a manager hands tasks to seven workers, progress shows on a dashboard, with Claude Code, Codex, Cursor and OpenCode supported
A local dashboard for running many agents across machines: memory, code graph and agent-to-agent messaging
A terminal workspace where several CLI agents like Codex, Claude and Gemini exchange messages and work on one task under human oversight
A Rust terminal task board: every task runs in its own git worktree and tmux window while Claude Code, Codex, Gemini CLI and other agents work in parallel
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| botmux (this entry) | no | 1,741 | |
| tlive | no | 215 | monitoring and approving Claude Code and Codex actions from Telegram or Feishu, with starting sessions from chat not the main job |
| HAPI | no | 5,282 | remote access to sessions through mobile apps and Web rather than through a messenger |
| Lark CLI | yes | 17,807 | the official Lark and Feishu CLI that gives an agent commands for messages and documents instead of driving the agent from chat |
README in short
The repository has bilingual documentation in Chinese and English, a five-minute setup guide, a description of the main scenarios and a table of supported agents. Separate sections cover safe storage of keys in `bots.json`, zero prompt injection, feedback on replies and Codex sessions with several login directories. Alongside are a `bots.json.example` sample, a `docs` directory describing the file sandbox, the model proxy mode and webhooks, plus tests and scripts that build the binary.