botmux: Run Claude Code and Codex From Inside Feishu, One Chat Session per CLI Process

What botmux Actually Bridges

botmux solves a specific pain: AI coding CLIs run on a developer's machine, but the developer is often away from that machine, on a phone or in a meeting. The README states the problem directly: the agent cannot notify you, and your phone cannot control it. botmux listens for Feishu or Lark messages, and for each new conversation it spawns a separate CLI process. Output from that process is streamed back in real time as Feishu cards. The project does not reimplement agent capabilities. It wraps the CLIs you already use, with more than 20 adapters listed, including claude-code, codex, gemini, cursor, opencode, copilot, grok, kimi, and others. The intended user is a developer or an oncall engineer who wants to start, watch, interrupt, and resume a coding session from within Feishu, without leaving the chat app.

One Session, One Process: The Core Architecture

The daemon's design is straightforward: each new chat session gets its own spawned CLI process. This is not a shared multiplexer where multiple chats fight over a single terminal. The README emphasizes that every DM, group, or topic creates an independent live-streaming session. That isolation has a practical consequence: you can run multiple different CLIs in the same group, each bound to a different bot, and have them review the same merge request independently. The project calls this multi-bot collaboration. Because each process is separate, the CLIs do not interfere with each other. The daemon also supports session adoption and relay. A local tmux session can be taken over from your phone with /adopt, and a session can be moved to another group with /relay, preserving the original process and memory. The architecture is simple, but it means the daemon is a long-running process that must stay alive for sessions to persist.

Getting It Running: Setup and Installation Paths

The README claims a five-minute setup. You install the npm package globally with npm install -g botmux, which requires Node 22 or newer. Then you run botmux setup. That command performs a Feishu QR code scan, creates the application, configures permissions, and publishes a version. If you prefer manual control, you can add --no-open-platform-auto to skip the automatic permission and publishing steps. After setup, botmux start launches the daemon, and botmux autostart enable sets it to start on boot. There is a second installation path that does not require Node at all. A self-contained binary can be downloaded with a curl command, and it includes its own runtime. The binary is platform-specific, supporting Linux and macOS on x64 and arm64. Windows is not supported natively; the README instructs Windows users to install inside WSL2, which reports as Linux and is treated as a first-class environment. The npm package bundles the binary and points ~/.botmux/bin/botmux at it, so there is only one botmux version on the system, avoiding conflicts between multiple Node installations.

Configuration: bots.json and the ebsd Special Case

Configuration lives in a file called bots.json. Each bot entry specifies a cliId, a workingDir, optional sandbox settings, and environment variables. The README gives a concrete example for the ebsd adapter, which has stricter requirements. ebsd uses an external service identity and native OMP session directories. The deployment must configure a Diag Gateway token and ByteCloud service account through restricted permission files, not through bots.json. The example shows environment variables pointing to token and key files, with a note that those files must be regular files with 0600 permissions owned by the account running botmux, and they cannot be symlinks. The workingDir should be a dedicated empty directory, and the repository is exposed read-only through EBSD_BOTMUX_REPOSITORY_ROOT. On Linux, enabling sandbox requires bubblewrap to be installed; if isolation setup fails, the daemon refuses to start. This is a meaningful operational constraint. For most other CLIs, configuration is simpler, but the ebsd example shows that some adapters carry heavy security assumptions.

Session-Level CLI Selection Has Sharp Edges

Before a session starts, you can use the /cli command to pick a CLI for that session, for example /cli codex. The README is explicit about a limitation: this selection switches only the bare CLI adapter. It does not inherit the bot configuration's wrapperCli, model, or startupCommands. That matters for CLIs that depend on wrappers or gateways like ttadk or aiden. Those CLIs will not work correctly with session-level selection, because they need the wrapper combination defined at the bot level. The README advises setting the bot's default configuration to the appropriate wrapper combination instead. Once a session has started, the CLI choice is frozen. Subsequent messages and session recovery continue using that same CLI. This is a deliberate design choice, but it means you cannot switch models mid-session, and you must plan your wrapper setup ahead of time.

Feedback and Policy Layers: A Modest Addition

The README describes an optional feedback mechanism for final answers, controlled per bot and disabled by default. You enable it with feedback.enabled: true in a bots.json entry. The feedback collects a fixed three-state semantic: positive, progress, or negative. The default buttons are labeled in Chinese, but the labels, style, order, and visible semantics are all configurable. Negative feedback can include a reason and an optional comment. The policy supports a hierarchy of local team, bot, and bot-scoped chat, with priority chat over bot over team. The Dashboard can preview the effective policy. Changes only affect newly delivered cards; already sent cards keep the snapshot from when they were sent. Data is stored locally in botmux-feedback.sqlite. An optional webhook can deliver turn.completed and feedback.revised events through a durable outbox. This feature is useful for teams that want to track answer quality, but it is clearly an add-on, not the core value of the project.

Real Limitations and Failure Modes

The most obvious limitation is platform support. The daemon depends on PTY, tmux, and Unix signals, so native Windows is impossible. The README says Windows users must use WSL2, which adds a layer of complexity for teams standardized on Windows. Another limitation is the reliance on a long-running daemon. If the daemon crashes or the machine reboots without autostart enabled, all active sessions are lost unless they were in tmux. The README mentions tmux session persistence as a feature, but it is an opt-in configuration. A third limitation is the sandbox requirement. On Linux, sandbox mode requires bubblewrap, and the daemon refuses to start if isolation setup fails. That is a hard failure, not a warning. Finally, the ebsd adapter has strict file permission and symlink constraints. If those are violated, the adapter will not work. These are concrete, documented boundaries, and they should be checked before deployment.

Alternatives and How They Differ

The closest alternative is running the AI coding CLI directly in a terminal or tmux session on your development machine. That approach gives you full control, no daemon, and no Feishu dependency. The difference is that you lose the mobile access and the chat-based interaction. You would need SSH from your phone, which works but is clunkier. Another alternative is using the CLI's built-in headless or server mode, if the CLI provides one. For example, Claude Code has a headless mode that can be driven programmatically, but it does not have a Feishu card interface. botmux's advantage is the streaming card UI and the multi-bot orchestration in a group. A third alternative is a generic chat-to-shell bridge like Hubot or a custom bot framework, but those do not have the 20+ prebuilt adapters or the session isolation that botmux provides. The trade-off is clear: botmux trades a simpler setup for a richer, Feishu-native experience.

Maintenance and Upgrade Considerations

The project is under active development, with three releases on the same day in the provided material: v3.18.6, v3.18.5, and v3.18.4. That release cadence suggests frequent fixes and feature additions. The npm package includes a self-contained binary, which means upgrades are handled through the normal npm update flow, but the binary is tied to the package version. The README does not describe a migration path for configuration files between versions, but the bots.json schema appears stable enough for the examples given. The license is MIT, which is permissive for commercial use, but it comes with no warranty. The documentation is extensive, with links to pages for cards, multi-bot, web terminal, adoption, scheduling, webhooks, oncall mode, voice summary, and sandbox. That breadth is a double-edged sword: it suggests a mature project, but it also means you need to read a lot of documentation to understand all the features and their constraints. Before adopting, you should check the changelog for recent breaking changes, especially around the adapter registry and the ebsd security model.

Editorial conclusion

Adopt botmux if your team works primarily inside Feishu or Lark, runs AI coding CLIs on Linux or macOS development machines, and needs to monitor or steer those sessions from a phone without SSH. Do not adopt it if you need native Windows support, if your security policy forbids running a daemon that spawns arbitrary shell processes, or if you rely on wrapper-based CLIs like ttadk or aiden that require session-level configuration inheritance. Before committing, verify that your target CLI is listed in src/adapters/cli/registry.ts, confirm that bubblewrap is installed if you enable sandbox on Linux, and test the setup flow with --no-open-platform-auto to see whether manual permission configuration is acceptable for your org. The core trade-off is clear: botmux gives you deep Feishu integration at the cost of a non-trivial local daemon, and you should judge whether that trade-off holds for your specific CLI and workflow.

Official sources

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