OpenMausBot: Build an actionable local AI team from Claude, Codex, and Grok CLIs
For developers with Claude, Codex, or Grok CLIs, it turns local agents into a chat team that can operate computers and apps.
GitHub milind-soni/OpenMausBot Updated 2026-10-30 Branch main Stars 7.5K Forks 1.1K
TypeScript Local-first AI agents Claude / Codex / Grok CLI macOS, Windows, Ubuntu 24.04

🧭 Decision Guide

Try it if you

  • 你已有 claude、codex 或 grok CLI,并希望复用现有登录和订阅
    README 的 Why 章节写明 Bots run on the `claude`, `codex`, and `grok` CLIs,以及 no new accounts
  • 你希望把 Markdown 团队文件接入 OpenMausBot,并让连接和 routines 默认保持受控
    README 的 Features / Install a complete team from one Markdown file 章节说明 Teams → Import、连接需批准、routines 初始暂停
  • 你要在脚本或 CI 中执行团队任务并读取机器可处理结果
    README 的 Run it from scripts and CI 章节提供 `openmausbot run`、`--json` 和退出码说明
  • 你的桌面环境是 macOS、Windows 或 Ubuntu 24.04 x64,并需要本地 harness server
    README 的 Quick start 要求列出这三类系统,并说明 released builds 内嵌 harness server

Skip it if you

  • 你需要 Ubuntu Wayland 的主机电脑控制能力
    README 的 Why 章节明确写明 Ubuntu Wayland host control remains disabled while issue #345 is resolved
  • 你的部署目标不是 GNOME 的 Ubuntu 24.04 桌面环境
    README 的 Quick start 标注 Ubuntu 24.04 构建为 Beta,GNOME 是 supported desktop
  • 你的安全要求禁止 API key 以明文写入本地配置文件
    README 的 Run from a terminal or on a server 章节写明 API keys are saved as plaintext in `config.json`
  • 你不能接受 Windows 安装器触发 SmartScreen 的 unknown publisher 提示
    README 的 Quick start 写明 Windows installer isn't code-signed yet

Requirements

  • 操作系统为 macOS、Windows 或 Ubuntu 24.04 x64
  • Node 24+、pnpm,以及至少一个已安装并登录的 `claude`、`codex` 或 `grok` CLI
  • 从源码运行需执行 `pnpm install`;桌面开发需保持 `pnpm dev:server` 和 `pnpm dev` 运行
  • Ubuntu 桌面构建要求 GNOME;Ubuntu 发行包提供 `.deb` 或 AppImage beta

First step (verbatim from README)

git clone https://github.com/milind-soni/OpenMausBot && cd OpenMausBot

Watch out

  • 首次运行必须先完成 AI access、登录或 API key、模型选择
    README 的 Run from a terminal or on a server 章节说明首次启动会引导这些选项
  • API 模式可能发送可计费的测试消息,setup 会在发送前询问
    README 的 Run from a terminal or on a server 章节明确说明 potentially billable test message
  • 手机不能直接使用 localhost 链接,远程访问需 pairing 或 Tailscale
    README 的 Run from a terminal or on a server 章节写明 phone cannot use a localhost link
  • 使用 `npx openmausbot serve` 时,`--tunnel` 需要先执行 `npx openmausbot login`
    README 的 Run from a terminal or on a server 章节给出 `--tunnel` 前置登录要求

Alternatives

  • Grok Bot:如果你需要 README 所称的原始 Grok Bot 体验,而不是本地优先和自带 CLI 的开源替代方案
    README 的 Why 章节
  • Meta Muse:如果你的比较范围是 README 明确列出的 Meta Muse 产品,而不是 OpenMausBot 的本地部署模型
    README 的项目介绍段落

Not stated in the README

  • README 未给出 Claude、Codex、Grok CLI 的最低兼容版本
  • README 未给出多 Agent 并发时的 CPU、内存或磁盘需求
  • README 未给出 500+ Composio 应用的逐项兼容范围和权限模型
  • README 未给出本地 VM、云端 Linux 桌面与主机控制的性能差异
  • README 未提供安全审计、漏洞响应 SLA 或 API key 加密计划
  • README 未说明 10 位贡献者与 5 个版本对应的长期维护节奏

💡 Deep Analysis

6
No I run Ubuntu 24.04 x64 with GNOME Wayland and want bots to control the host directly instead of using a cloud desktop or Local VM. Does OpenMausBot meet this constraint?
For: A Linux engineer on Ubuntu 24.04 x64 with GNOME Wayland who wants agents to operate the local desktop

No, not for this exact constraint. The README explicitly says Ubuntu Wayland host control is disabled, so you would need a cloud desktop or an isolated Local VM instead.

  • Ubuntu 24.04 x64 has .deb and AppImage packages, but the Linux desktop build is still marked Beta and GNOME is the supported desktop environment.
  • Bots can still use a cloud Linux desktop or an isolated Local VM, but those are not direct control of the Wayland host.
  • Host control is documented for macOS and Ubuntu Xorg after explicit opt-in. Wayland remains disabled while issue #345 is being resolved.

If direct control of the local Wayland desktop is mandatory, this project does not currently satisfy the requirement. The README gives no resolution date for issue #345.

  • Why: "Ubuntu Wayland host control remains disabled while issue #345 is resolved"
  • Why: "Host control is available on macOS and Ubuntu Xorg after explicit opt-in"
  • Quick start: Ubuntu 24.04 x64; "Beta; GNOME is the supported desktop"
  • Why: cloud Linux desktop and isolated Local VM are supported
Not stated in the README:The README gives no expected release or date for fixing issue #345.;It does not say whether another direct-host-control implementation is available under Wayland.
No I need to self-host OpenMausBot on a VPS, but our policy forbids plaintext API-key storage. Even with file permissions set to 0600, can I directly use its API mode?
For: An internal automation administrator deploying to a VPS or self-hosted server who requires API keys not to be stored in plaintext

No, not directly. The README explicitly says that API keys are saved as plaintext in config.json; 0600 restricts Unix file access but does not satisfy a policy requiring secrets not to be stored in plaintext.

  • The terminal mode supports Node 24+ and server deployment, but server deployment does not change the documented credential-storage behavior.
  • openmausbot setup can reconfigure the model and access method, yet the README still states: “API keys are saved as plaintext, not encrypted.”
  • Transcripts, events, and configuration are stored under ~/.openmausbot, so a VPS also requires controls for disk access, backups, and administrator access.

Using an already authenticated CLI may avoid this API-key path, but the README does not document how CLI credentials are stored and does not describe integration with an external secret manager.

  • Run from a terminal or on a server: "API keys are saved as plaintext, not encrypted, in private `config.json` (`0600` on Unix)."
  • Run from a terminal or on a server: supports global npm installation and server execution
  • Why: "Transcripts, keys, and events live in `~/.openmausbot`, not a cloud."
  • Project insight: self-hosted enterprise use still requires encryption, access control, backup, audit, and key rotation
openmausbot setup
Not stated in the README:The README does not state whether CLI login credentials are encrypted, how they are rotated, or whether an external secret manager is supported.;It does not describe built-in disk encryption, audit logging, or a multi-user permission model for VPS deployments.
Yes I am already logged into Claude Code on macOS and want multiple bots with different models, separate memories, and their own computer environments. Is OpenMausBot suitable for me?
For: A solo developer already using Claude Code, Codex, or Grok CLI who wants a chat interface for managing multiple local agents

Yes. It is designed for this exact setup: it organizes existing CLI agents into separate chat-like contacts instead of replacing them with a new model account.

  • Every sidebar bot is a real agent with its own personality, model, thread memory, computer, and connected apps. The documented engines include locally installed claude, codex, and grok CLIs.
  • macOS support covers both Apple silicon and Intel, and released desktop builds embed the harness server, so a separate server setup is not required.
  • A bot can use a cloud Linux desktop, an isolated Local VM, or, after explicit opt-in, the macOS host computer. Important actions can require approval.

You still depend on the CLI login, subscription permissions, and network. The README does not specify whether context and tool behavior remain identical when moving a bot between different engines.

  • Why: "Bots run on the `claude`, `codex`, and `grok` CLIs installed on your own machine"
  • README introduction: each sidebar bot has its own personality, model, cloud computer, and connected apps
  • Quick start: macOS Apple silicon and Intel builds; "the harness server is embedded"
  • Why: "Host control is available on macOS ... after explicit opt-in"
npm install -g openmausbot
Not stated in the README:The README does not state whether history, tool-call formats, and memory remain fully compatible when switching between Claude, Codex, and Grok.;It does not specify a stable bot count or concurrency limit for one macOS host.
Yes I want to access and operate OpenMausBot from a phone while it runs on another Windows, macOS, or Ubuntu host. I can use Tailscale but cannot expose localhost to the phone. Is this deployment feasible?
For: A developer who wants phone access to a local or remote OpenMausBot instance through protected HTTPS or Tailscale

Yes, provided that pairing uses Tailscale, a protected HTTPS endpoint, or your own HTTPS reverse proxy. A phone cannot connect directly to a localhost URL.

  • The README supports pairing a desktop client with another Windows, macOS, or Ubuntu host, and supports mobile browsers, native Android/iOS clients, and an installable phone web app.
  • The terminal onboarding flow can configure phone access. Android uses a QR app link, while iOS accepts the app link or web link.
  • Remote access must use an explicitly approved managed HTTPS endpoint protected by pairing, an existing Tailscale connection, or your own HTTPS reverse proxy. --local can ignore saved remote access for one launch.

This is suitable for remote access, but it does not automatically provide a secure public endpoint. The README does not specify the reverse proxy authentication implementation, device concurrency limits, or mobile support for every desktop feature.

  • Run from a terminal or on a server: "A phone cannot use a localhost link."
  • Run from a terminal or on a server: managed public HTTPS, Tailscale, or an HTTPS reverse proxy
  • Quick start: any desktop build can pair with another Windows, macOS, or Ubuntu host over Tailscale
  • Run from a terminal or on a server: Android QR app link and iOS app or web link
openmausbot
Not stated in the README:The README does not specify the exact authentication, TLS, or access-control implementation required for a self-managed reverse proxy.;It does not state whether mobile clients support every agent approval, computer-control, and connected-app feature.
Yes I maintain a Node 24+ automation environment and need to start bots from scripts or CI, wait for collaborators, and export JSON results. Is OpenMausBot suitable as a headless execution layer?
For: An automation engineer using Node 24+ who needs to drive AI agents from scripts, CI, and scheduled jobs

Yes. The README explicitly provides terminal execution, CLI orchestration, and JSON output with exit codes for automation.

  • You can install it globally with npm or run it through npx; the first launch guides AI access, model selection, and optional phone pairing.
  • The project supports applying teams, running agent tasks, waiting for agents and collaborators to finish, and exporting results. JSON output and exit codes are intended for automation.
  • The harness server owns agent processes, events, and sessions, while the UI and headless CLI share the workspace model.
  • The documented requirements include Node 24 or newer and at least one installed and authenticated claude, codex, or grok CLI.

However, the README does not define CI retry, timeout, idempotency, or partial-completion semantics. Those details require validation outside the documented interface.

  • Run from a terminal or on a server: "With Node 24 or newer, install once and run"
  • Project insight: supports team apply, run, waiting for collaborators, result export, JSON output, and exit codes
  • Quick start: at least one installed and logged-in `claude`, `codex`, or `grok` CLI
  • Project insight: the local harness server manages agent processes, transcripts, and events
npm install -g openmausbot
Not stated in the README:The omitted CLI sections do not provide the complete command syntax, JSON schema, timeout options, or exit-code definitions.;The README does not explain resource isolation when multiple teams or tasks run concurrently in CI.
It depends I want to package bots, a Chief of Staff, channels, playbooks, and recurring tasks as reviewable Markdown for a small team using Claude or Codex CLI. Is OpenMausBot suitable for this portable configuration model?
For: A technical lead who wants to distribute bots, a Chief of Staff, channels, and playbooks to a small team as a Markdown team package

It depends. OpenMausBot is suitable for distributing role and workflow definitions, but the Markdown package should not be treated as a complete delivery of credentials, permissions, or runtime environments.

  • The project supports Markdown team packages with YAML frontmatter describing bots, a Chief of Staff, channels, playbooks, connection lists, and recurring tasks.
  • Imports are reviewable; connections are off by default and recurring tasks are paused by default. Packages do not carry credentials, sessions, permissions, or computer access, which improves portability and reviewability.
  • The receiving user still needs an installed and authenticated claude, codex, or grok CLI, plus compatible model access and computer capabilities.

It is therefore best understood as a configuration and workflow blueprint, not a full copy of a running team. The README does not explain how differences in model permissions are detected or reported during import.

  • Project insight: team packages use Markdown with YAML frontmatter for bots, Chief of Staff, channels, playbooks, connection lists, and recurring tasks
  • Project insight: imports are reviewable; connections are off and recurring tasks are paused by default
  • Project insight: packages do not carry credentials, sessions, permissions, or computer access
  • Why: depends on locally installed and authenticated `claude`, `codex`, and `grok` CLIs
Not stated in the README:The README does not provide the complete team-package schema, version-compatibility rules, or conflict-resolution behavior.;It does not state whether imports check the recipient's CLI version, model subscription, or connected-app permissions.

✨ Highlights

  • Supports claude, codex, and grok CLIs with existing logins and subscriptions
  • A 127.0.0.1 harness server keeps agent processes and data local
  • Each bot can connect to a cloud Linux desktop, Local VM, or host computer
  • Teams can be imported from Markdown and run in CI with openmausbot
  • Ubuntu Wayland host control remains disabled while issue #345 is unresolved

🔧 Engineering

  • Manage local Claude or Codex agents in a chat sidebar, each with its own model and memory
  • Import Markdown teams driven by YAML frontmatter through Teams → Import
  • openmausbot run supports team collaboration, --json output, and --export exports
  • Composio provides 500+ app connections, enabled only after user approval

⚠️ Risks

  • API keys are stored as plaintext in config.json with Unix mode 0600
  • The Windows x64 installer is not code-signed, so SmartScreen shows unknown publisher
  • The Ubuntu 24.04 build is beta and supports the GNOME desktop
  • Host control on macOS and Ubuntu Xorg still requires explicit opt-in

👥 For who?

  • Individual developers who already have claude, codex, or grok logged in
  • TypeScript teams that need to connect multi-agent teams to scripts and CI
  • Desktop users running macOS, Windows, or Ubuntu 24.04 x64