Codex Agent Bus

Agent-driven install: launch Codex or Claude Code in your terminal and tell it:

Install https://github.com/georgepullen/codex-agent-bus.git by following the instructions in this README. Verify codex-agent-bus brief works in one of my repos, and install the included Codex skill if I use Codex skills.

Codex Agent Bus is a local-first coordination CLI for running multiple coding agents in one repository through CMUX terminal surfaces. It gives agents a shared, durable project notice board: heartbeats, file claims, direct messages, broadcasts, wake pointers, and blocking delegated jobs or reviews.

The project intentionally focuses on CMUX CLI multi-agent orchestration. It does not manage account profiles, authentication, cloud services, or secrets.

What It Provides

• brief: register the current agent and see nearby peers, claims, and unread notices.
• claim / release: reserve file or directory scopes before editing.
• send, broadcast, inbox, read: durable mailbox messages in repo-local state.
• wake: notify an idle peer about a direct bus message without pasting the message body.
• run: launch a bounded same-repo worker agent through CMUX.
• review: launch a read-only review worker and block until the Markdown result is ready.
• begin-job, finish-job, wait, result: durable job lifecycle commands for workers and supervisors.

State is stored under ~/.codex-agent-bus by default and is scoped by profile label plus git root. Repos and worktrees get separate state automatically.

Requirements

• Python 3.9 or newer.
• git.
• cmux on PATH for worker launch, wake, split, screen, and notification features.
• A coding-agent launcher on PATH; defaults to codex.
• Worker agents must run in non-interactive approval mode, often called YOLO mode or danger/full-access mode. If commands require approval prompts, the worker can stall mid-job.

The basic coordination commands (brief, claim, messages, dry-run jobs) work without a live CMUX session. Launching workers requires running inside CMUX.

Install

Use one of these:

pipx install git+https://github.com/georgepullen/codex-agent-bus.git

uv tool install git+https://github.com/georgepullen/codex-agent-bus.git

For editable local development:

git clone https://github.com/georgepullen/codex-agent-bus.git
cd codex-agent-bus
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
pip install -e .

Verify:

codex-agent-bus --help
codex-agent-bus brief --task "install check"

Agent Launcher

Worker launch defaults to codex. Override the launch command explicitly for your environment:

export CODEX_AGENT_BUS_LAUNCH_CMD="codex"

For Claude Code:

export CODEX_AGENT_BUS_LAUNCH_CMD="claude"

Make sure the command starts the agent in non-interactive approval mode. For Codex this is commonly YOLO mode; for Claude Code use the equivalent danger/approval-bypass mode for your local setup.

If the generated worker prompt needs a non-default command name for the bus itself, set:

export CODEX_AGENT_BUS_BIN="codex-agent-bus"

Install The Codex Skill

The pipx and uv tool commands install the CLI. They do not install the Codex skill assets into CODEX_HOME. If you use Codex skills, clone this repo or use an existing checkout, then run:

scripts/install-skill

Or manually place skills/codex-agent-bus under:

$CODEX_HOME/skills/codex-agent-bus

Then restart Codex or open a new session and ask it to use the codex-agent-bus skill.

Everyday Use

At the beginning of meaningful work in a repo:

codex-agent-bus brief --task "fix auth test"

Before editing a path another agent might touch:

codex-agent-bus claim --path src/auth --task "fix login validation"

After finishing:

codex-agent-bus release --all

Ask all active peers who owns unexpected changes:

codex-agent-bus broadcast \
  --type ownership_query \
  --summary "Who owns src/auth/login.ts?" \
  --path src/auth/login.ts \
  --message "I see unstaged edits in src/auth/login.ts. Are these yours?"

Launch a blocking review:

codex-agent-bus review \
  --task "review auth validation fix" \
  --scope src/auth \
  --verification "unit tests passed" \
  --concern "check for accidental behavior changes" \
  --wait-timeout 300

Launch a bounded worker:

codex-agent-bus run \
  --task "inspect flaky login test and report likely cause" \
  --scope tests/login.test.ts \
  --wait-timeout 300

Environment

CODEX_AGENT_BUS_PROFILE       Optional state partition label. Defaults to "default".
CODEX_AGENT_BUS_ROOT          Explicit shared root for non-git directory trees.
CODEX_AGENT_BUS_STATE_HOME    State directory. Defaults to ~/.codex-agent-bus.
CODEX_AGENT_BUS_ID            Explicit current agent id.
CODEX_AGENT_BUS_LAUNCH_CMD    Command used to launch worker agents. Defaults to codex.
CODEX_AGENT_BUS_BIN           Command printed inside generated worker instructions. Defaults to codex-agent-bus.
CMUX_BIN                      CMUX executable. Defaults to cmux.
CMUX_WORKSPACE_ID             Optional current workspace hint supplied by launchers.
CMUX_SURFACE_ID               Optional current surface hint supplied by launchers.

Public Safety

The bus stores coordination metadata, task text, paths, and Markdown job results. Do not put secrets in task descriptions, messages, or job results. The CLI does not copy auth files, profile homes, terminal history, or MCP credentials.