botmux: run Claude Code, Codex and Gemini from Feishu/Lark chats

What botmux solves for teams whose agents run on a dev box

The README frames the problem in three parts. First, the CLI runs on a development machine while the person is on a phone, so agent output has no notification path. Second, the CLI has no awareness of Feishu context, meaning a bot pulled into a topic group or an oncall group cannot start work in the right repository from a mention. Third, one agent is not enough for review work, and the project's answer is to put several bots with different CLIs in the same group and address them by @mention.

The audience is narrow and specific: engineers who already run Claude Code, Codex, Gemini, OpenCode or one of the other listed adapters locally, and whose organisation uses Feishu or Lark as its chat platform. If your team is on Slack, this project does not address you. The README states plainly that botmux does not rebuild agent capability; it bridges tools you already use.

One Feishu message, one CLI process, one streaming card

The architecture is a daemon plus per-session processes. A daemon listens for Feishu messages, and for each new session it spawns an independent session process. Output from the CLI is streamed back as a Feishu card that refreshes in place, and the project also exposes an interactive web terminal for writing into the session rather than only reading it.

Adapter selection is configuration, not code. A bots.json entry carries a cliId, a workingDir and optional env, and the README points to src/adapters/cli/registry.ts as the authoritative list of current cliId values. Two classes of adapter exist: local CLIs, which run as isolated processes that you can reach with tmux attach, and API or cloud agents such as Mira and riff, which are reached over the network rather than as local processes. mojo is described as API driven with tool execution on the host by default, switchable with cloud: true.

Session state has a lifecycle worth understanding before you deploy. A session can be adopted from a local tmux run with /adopt, and /relay moves an entire session, original process and memory included, into another group. CLI selection freezes once a session starts, so later messages and recovery continue with the same CLI. That freezing is deliberate and it is also the source of the sharpest constraint in the project.

Installing botmux and starting a first session

The npm route requires Node 22 or newer for the package install itself, but the package ships a self-contained binary for the matching os/arch, so no native modules are compiled and no Python, node-gyp or compiler is needed. Installation points ~/.botmux/bin/botmux at that binary, and the install log tells you to put ~/.botmux/bin on PATH.

npm install -g botmux
botmux setup
botmux start

botmux setup is a single Feishu scan-code flow that creates the application, configures permissions and publishes it. Passing --no-open-platform-auto creates the application only and skips the automatic permission and publish steps, which you then complete by hand; pasting credentials manually is a separate option inside setup. botmux start launches the daemon, and botmux autostart enable sets it to start on boot.

If you would rather not install Node at all, the same binary can be fetched directly. The README gives this form for macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/deepcoldy/botmux/master/install.sh | sh
botmux setup
botmux start

The script installs to ~/.botmux/bin/botmux, honours BOTMUX_INSTALL_DIR, pulls the matching binary for your OS and architecture, and verifies a SHA-256 checksum. Command usage is identical to the npm version.

After the daemon is up, the quickstart path is to message the bot directly, or run botmux dashboard to pull the bot into a group and start talking there. A per-session CLI switch is available before the session starts:

/cli codex

The README is explicit that this switches the bare CLI adapter only. It does not inherit wrapperCli, model or startupCommands from the bot configuration, so CLIs that need a wrapper or gateway to launch, such as ttadk or aiden, should be set as the bot default instead of switched per session.

The wrapperCli trap in /cli and where sessions stop being portable

The most consequential limitation is the one attached to /cli. Because the session-level switch ignores wrapperCli, model and startupCommands, a CLI that only starts through a wrapper or gateway will not start correctly when selected this way. The README's own remedy is to configure the bot default as the wrapper combination instead. That is a fine answer for a fixed setup, but it means the convenience feature is unavailable precisely for the adapters that need the most configuration.

The freeze after session start compounds this. Once a session is running, the CLI choice is fixed, and subsequent messages and recovery reuse it. If you pick the wrong adapter, the recovery path does not let you change your mind mid-session; you start a new session. Combined with the fact that /relay moves the original process and memory rather than re-creating the session under new settings, moving a session to another group preserves the original choice as well.

Platform support is the second hard boundary. The npm package installs binaries for linux and macOS on x64 and arm64. Windows is directed to WSL2, and the README explains why: the daemon depends on PTY, tmux and Unix signals, so native Windows cannot run it. WSL2 reports as linux and is described as a fully supported first-class environment. Unsupported platforms fail loudly at install time rather than installing a command that cannot run, which is the right behaviour but still means the tool is unavailable there.

The ebsd adapter shows a third kind of constraint. It uses a separate external service identity and a native OMP session directory, and the deployment must configure a Diag Gateway token and a ByteCloud service account through restricted permission files. Three key files must be 0600 regular files owned by the account running BotMux, not symlinks, and neither the file contents nor the AK/SK or Gateway token may be written into bots.json. workingDir should be a dedicated empty directory, with repositories exposed read-only through EBSD_BOTMUX_REPOSITORY_ROOT. On Linux, enabling sandbox requires bubblewrap, and the README states that a failed isolation setup refuses to start. That is a deliberate fail-closed design, and it means a missing bubblewrap turns into a startup failure rather than a silent downgrade.

How botmux differs from a chat SDK that calls a model API

The obvious alternative for a team wanting an agent in chat is to build on a chat SDK and call a model API directly, or to use a hosted assistant that already lives inside Feishu. The difference in approach is where the agent runs. A chat SDK integration runs the model in the cloud and holds conversation state in your service; botmux runs the CLI on your machine and holds the session in a process there, with the chat platform as the display and control surface.

That matters when the agent needs your working tree, your credentials and your local toolchain. It also matters for inspection: because local adapters are isolated processes, tmux attach gives you the same session the bot is driving. A cloud API integration has no equivalent, since there is no local process to attach to. The trade-off runs the other way as well. botmux inherits the operational requirements of the host, which is exactly why Windows without WSL2 is out, and why the daemon needs PTY and Unix signals. A hosted assistant has none of those requirements and also none of that access.

The project does ship some API-driven adapters, so the split is not absolute. Mira and riff connect over API or remote access rather than as local processes, and mojo is API driven with host-side tool execution by default. The distinction the README draws is between local process isolation and API or cloud access, and you should decide which side of it your workflow needs before adopting.

Maintenance, licence and what upgrades actually cost

The repository is not archived, and the last push was on 2026-08-29, the same day as the v3.18.6 release. Three releases landed that day: v3.18.4, v3.18.5 and v3.18.6. That is a rapid cadence, and it is visible in the tooling as well, with separate build, audit, dashboard bundle and binary verification scripts in package.json.

Upgrade cost is lower than it looks, for one specific reason the README calls out: the npm package ships a self-contained binary per platform, and installation points a single ~/.botmux/bin/botmux at it. The README contrasts this with the situation it avoids, where two Node versions each carry their own global botmux and you cannot tell which one was updated. One installed version means an upgrade replaces one artefact. The direct install.sh path verifies SHA-256, so a corrupted or mismatched download fails rather than installing.

The licence is MIT, which permits commercial and closed-source use and modification, with the usual requirement to preserve the copyright notice and licence text. Nothing in the repository suggests additional restrictions for the core project, but the ebsd adapter depends on external services and credentials configured outside the repository, and those are governed by their own terms, not by the MIT grant. Treat adapter-specific service access as a separate review.

Editorial conclusion

Adopt botmux if your coding agents already run on a Linux or macOS host and your team lives in Feishu or Lark: the per-session process model and the tmux attach path give you a real terminal, not a wrapper around a chat API. Skip it if you need native Windows, or if you want a hosted multi-tenant service, since the daemon expects PTY, tmux and Unix signals on the machine that runs your CLIs. Before rolling it out, verify two things: that src/adapters/cli/registry.ts still lists the cliId you intend to use, and that the bot configuration you pick either avoids wrapperCli or sets it explicitly, because /cli switches the bare adapter only.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes