Codex CLI Bus

Codex CLI Bus 是一个本地文件型消息总线，用来协调多个 Codex CLI agent。它可以让一个主 Codex CLI 注册自己、启动 worker、派发任务、发送消息、查看状态，并通过共享 mailbox 接收结果。

这个项目既可以作为普通 Node.js CLI 工具使用，也可以作为 Codex CLI 插件使用。作为插件安装后，Codex 可以把自然语言请求转换为结构化的 MCP 工具调用，例如“启动一个 cli-b 跑测试并回报结果”。

安装和加入插件

1. 下载 npm 包

npm install -g codex-cli-bus

如果你的 npm registry 指向镜像源且还没有同步到最新版本，可以指定官方源：

npm install -g codex-cli-bus --registry=https://registry.npmjs.org/

确认命令可用：

codex-cli-bus help

2. 加入 Codex CLI 插件

执行一键安装：

codex-cli-bus install-plugin

这个命令会自动完成：

在 ~/.codex-cli-bus/plugin-marketplace 生成本地 Codex marketplace。
在 marketplace 中生成 codex-cli-bus 插件目录。
写入 MCP Server 配置。
执行 codex plugin marketplace add ...。
执行 codex plugin add codex-cli-bus@codex-cli-bus-local。

检查插件是否加入成功：

codex plugin marketplace list
codex plugin list --marketplace codex-cli-bus-local

正常情况下会看到 codex-cli-bus-local marketplace，以及 codex-cli-bus 插件。

安装后重新打开一个新的 Codex CLI 会话，让插件、技能和 MCP Server 生效。然后可以直接对 Codex 说：

查看所有 Codex CLI agent 当前状态。

或者：

启动 cli-b 常驻 worker，让它自动领取后续任务。

3. 更新插件

npm install -g codex-cli-bus@latest --registry=https://registry.npmjs.org/
codex-cli-bus install-plugin

更新后同样需要重新打开一个新的 Codex CLI 会话。

只想预览安装计划、不真正写入或安装时：

codex-cli-bus install-plugin --dry-run

功能特性

本地文件协议，无需数据库或远程服务。
支持注册、心跳、状态查询、任务派发、消息回复和事件日志。
支持启动持久 worker，自动领取后续任务。
支持启动交互式 Codex CLI 或一次性的 codex exec worker。
支持 owner-local agent 命名，多个 controller 可以各自拥有同名 worker。
提供 MCP Server，可作为 Codex CLI 插件被自然语言调用。

运行要求

Node.js 18 或更高版本。
如果要启动真实 Codex worker，需要本机已安装并可执行 codex 命令。
如果要作为 Codex 插件使用，需要本机 Codex CLI 支持插件和 MCP Server。

本项目没有运行时 npm 依赖。npm 包会提供两个命令：

codex-cli-bus
codex-cli-bus-mcp

源码开发时也可以用等价命令：

node scripts/codex-cli-bus.mjs
node scripts/mcp-server.mjs

目录结构

codex-cli-bus/
  .codex-plugin/
    plugin.json              # Codex 插件元信息
  .mcp.json                  # MCP Server 配置
  docs/
    ARCHITECTURE.md          # 架构与协议说明
  scripts/
    codex-cli-bus.mjs        # 核心 CLI、文件协议、worker loop
    mcp-server.mjs           # MCP stdio server
    protocol.schema.json     # 协议 JSON schema
    codex-cli-bus.test.mjs   # 测试
  skills/
    cli-bus/
      SKILL.md               # Codex 使用该插件时加载的技能说明
  package.json
  README.md

运行时数据默认写入：

~/.codex-cli-bus

也可以为测试或演示指定独立目录：

export CODEX_CLI_BUS_HOME="$PWD/.bus"

快速开始

进入项目目录后，先检查脚本是否可用：

npm run check
npm test

注册两个本地 agent：

codex-cli-bus register --agent cli-a --label controller
codex-cli-bus register --agent cli-b --label worker

从 cli-a 给 cli-b 发送任务：

codex-cli-bus send \
  --from cli-a \
  --to cli-b \
  --type task \
  --text "Run the focused test suite and report the result."

让 cli-b 领取任务：

codex-cli-bus poll --agent cli-b --claim

领取后会返回一个 message_id，用它回复任务结果：

codex-cli-bus reply \
  --from cli-b \
  --message msg_x \
  --text "Focused tests passed."

最后让 cli-a 查看回复：

codex-cli-bus poll --agent cli-a --claim

其中 msg_x 需要替换成实际返回的消息 ID。

常用命令

查看帮助：

codex-cli-bus help

列出 agent：

codex-cli-bus list
codex-cli-bus list --viewer cli-a
codex-cli-bus list --owner cli-a

查看单个 agent 或任务：

codex-cli-bus status --agent cli-b
codex-cli-bus status --task task_x

发送普通消息：

codex-cli-bus send \
  --from cli-a \
  --to cli-b \
  --type message \
  --text "The branch is ready. Please re-check."

查看任务列表：

codex-cli-bus tasks --viewer cli-a --limit 20

查看事件日志：

codex-cli-bus events --viewer cli-a --limit 20

停止一个 worker：

codex-cli-bus stop-agent \
  --from cli-a \
  --agent cli-b \
  --reason "No longer needed."

启动 Worker

如果希望 cli-b 常驻运行，并自动领取后续任务，可以使用：

codex-cli-bus start-worker \
  --from cli-a \
  --agent cli-b \
  --workspace .

这个命令会把 worker 存为 owner-local agent。用户看到的是 cli-b，内部实际 ID 是：

cli-a.cli-b

如果同一个 owner 下的 cli-b 已经在线，默认会复用已有 worker。需要明确替换时再加：

codex-cli-bus start-worker \
  --from cli-a \
  --agent cli-b \
  --workspace . \
  --replace

调试时可以在前台运行 worker loop：

codex-cli-bus worker-loop \
  --agent cli-b \
  --workspace .

启动一个交互式 Codex CLI worker：

codex-cli-bus launch-codex \
  --from cli-a \
  --agent cli-b \
  --workspace . \
  --open-terminal \
  --text "Run npm test and reply with the failure summary."

启动一个一次性的非交互式 codex exec worker：

codex-cli-bus spawn-codex \
  --from cli-a \
  --agent cli-b \
  --workspace . \
  --text "Run npm test and reply with the failure summary."

worker 日志会写入：

$CODEX_CLI_BUS_HOME/logs/

手动插件安装

仓库中已经包含插件配置：

.codex-plugin/plugin.json
.mcp.json
skills/cli-bus/SKILL.md
scripts/mcp-server.mjs

正常使用推荐前面的 codex-cli-bus install-plugin。如果你需要手动维护 marketplace，目录通常长这样：

Cli-demo/
  .agents/
    plugins/
      marketplace.json
  codex-cli-bus/
    .codex-plugin/
      plugin.json

marketplace.json 中需要包含 codex-cli-bus 这一项，例如：

{
  "name": "cli-demo",
  "interface": {
    "displayName": "CLI Demo"
  },
  "plugins": [
    {
      "name": "codex-cli-bus",
      "source": {
        "source": "local",
        "path": "./codex-cli-bus"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

如果你保持上面的目录结构，在 codex-cli-bus 目录里可以手动执行：

codex plugin marketplace add ..
codex plugin list --marketplace cli-demo
codex plugin add codex-cli-bus@cli-demo

如果你是在别的位置维护 marketplace，把 .. 换成包含 .agents/plugins/marketplace.json 的目录即可。

安装后重新打开一个 Codex CLI 会话，让插件、技能和 MCP Server 生效。之后可以直接用自然语言操作：

启动一个叫 cli-b 的 Codex CLI，让它在当前目录跑 npm test，然后把结果回给我。

启动 cli-b 常驻 worker，让它自动领取后续任务。

看看所有 CLI agent 当前在做什么，谁有未处理消息。

给 cli-b 发消息：我刚改了协议，让它重新检查状态。

如果从 GitHub 克隆后使用手动 marketplace 安装，请检查 .mcp.json 是否适合你的安装方式。npm 一键安装会生成独立的插件目录和 MCP 配置，不需要手动改路径。

开发或演示时也可以设置：

export CODEX_CLI_BUS_HOME="$PWD/.bus"

手动 marketplace 安装的插件更新后可以重新执行：

codex plugin add codex-cli-bus@cli-demo

然后开启新的 Codex CLI 会话测试更新后的插件。

Agent 命名规则

controller 的 ID 是全局的，例如：

cli-a
controller
controller-laptop

child worker 的名字是 owner-local 的。例如 cli-a 启动本地 cli-b 后：

用户可见名: cli-b
内部 agent_id: cli-a.cli-b
owner_agent_id: cli-a
local_agent_id: cli-b

另一个 controller 也可以启动自己的 cli-b，内部会变成：

cli-c.cli-b

因此不同 controller 的 worker 不会共享 mailbox、任务和状态。多个主 CLI 同时使用时，建议给每个 controller 设置不同的 CODEX_AGENT_ID：

export CODEX_AGENT_ID=cli-a

文件协议

总线数据写在 CODEX_CLI_BUS_HOME 下：

CODEX_CLI_BUS_HOME/
  agents/
    records/                 # agent 注册记录
    ownership/               # owner-child 映射
  mailboxes/
    <agent>/
      inbox/                 # 待领取消息
      processing/            # 已领取待处理消息
      archive/               # 已完成消息
  tasks/                     # task 生命周期记录
  events/
    events.jsonl             # 事件日志
  logs/                      # worker stdout/stderr 日志
  tmp/

协议字段定义见 scripts/protocol.schema.json。

开发

语法检查：

npm run check

运行测试：

npm test

架构和协议细节见 docs/ARCHITECTURE.md。

GitHub 上传建议

上传前建议确认以下内容：

.bus/、node_modules/、.DS_Store 已在 .gitignore 中忽略。
不要提交运行时生成的 mailbox、task、event、log 文件。
发布 npm 前先确认包名可用；如果 codex-cli-bus 已被占用，可以改成 scoped 包名，例如 @your-name/codex-cli-bus。
公开发布 npm 包前，建议补充 repository、license 和作者信息。
先执行 npm run check 和 npm test，确保脚本和协议测试通过。

License

当前仓库还没有声明 License。公开发布到 GitHub 前，建议根据你的使用目标添加一个 LICENSE 文件，例如 MIT、Apache-2.0 或其他许可证。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Codex CLI Bus

安装和加入插件

1. 下载 npm 包

2. 加入 Codex CLI 插件

3. 更新插件

功能特性

运行要求

目录结构

快速开始

常用命令

启动 Worker

手动插件安装

Agent 命名规则

文件协议

开发

GitHub 上传建议

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.codex-plugin		.codex-plugin
docs		docs
scripts		scripts
skills/cli-bus		skills/cli-bus
.gitignore		.gitignore
.mcp.json		.mcp.json
README.md		README.md
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

Codex CLI Bus

安装和加入插件

1. 下载 npm 包

2. 加入 Codex CLI 插件

3. 更新插件

功能特性

运行要求

目录结构

快速开始

常用命令

启动 Worker

手动插件安装

Agent 命名规则

文件协议

开发

GitHub 上传建议

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages