brgr-cli 2.15.22

Let Codex or Claude Code hand work to other coding agents, each in its own Herdr pane: the brgr CLI and Herdr plugin.
brgr-cli-2.15.22 is not a library.

brgr

Hand work to any coding agent CLI and get back a sealed result that you decide on. The work outlives the session, pane or quota that started it.

Today brgr needs Herdr: each worker runs in its own Herdr pane beside you, without anyone clicking through its prompts.

Claude Code asks brgr for three Claude Code workers. They open stacked beside it, report back, are accepted, and their panes close.

Above: one request to Claude Code. brgr opens three Claude Code workers beside it, each worker's report comes back as a FROM BRGR notice, Claude accepts it, and brgr closes that worker's pane. Shown at 2x speed.

brgr brings the orchestration part of Orca, a desktop app for running many coding agents, to Herdr. Your agent stays the one that decides. brgr starts the workers, clicks through the trust and continue prompts that would stop them, and hands every result back for an explicit accept or reject.

What it does

  • Workers in panes, not in the background. Each worker is the harness's own TUI in a Herdr pane. The first one splits your pane. Later ones stack under it at equal heights while you keep your half, and every brgr command evens the column out again. When a result is accepted or rejected its pane closes, and its worktree is removed once nothing in it would be lost (--keep-worktree keeps it).
  • Unattended. brgr accepts workspace trust, "press Enter to continue" notices, and Claude Code's bypass warning and new-MCP-server prompt. It skips update offers. A screen it does not recognise is reported with its text and fails the run after three minutes, instead of waiting forever.
  • Results you decide on. Each worker writes a report that brgr seals. brgr types a FROM BRGR notice into your agent's pane, and the agent reads the result and accepts or rejects it. A diff is applied only after an explicit accept.
  • Failures reach you. A failed or lost run sends a failure notice with the reason. Every brgr command repeats it until you acknowledge it.
  • Talk both ways. Owner and worker exchange questions and replies, workers can start their own child workers, and sibling workers can debate when you ask for it.

brgr calls each registered worker CLI a harness, and supports them in tiers. Tier 1 is Claude Code, Codex CLI, Cursor CLI and Devin CLI. Tier 2 is Command Code, OMP, OpenCode and Cline. Tier 3 is GitHub Copilot CLI, Gemini CLI and Pi. The agent that starts workers, the owner, can be a Codex, Claude Code or Cursor session.

Run brgr config edit in a terminal to manage aliases and per-harness default models. Agents and scripts can use commands such as brgr config alias list and brgr config set model MODEL --harness ID.

Workers always run with full permissions (--yolo, --dangerously-skip-permissions and equivalents). That is the point of unattended orchestration, so only point brgr at code you trust. A clean Git repository gets a separate worktree for each task.

Requirements

  • Apple Silicon Mac with macOS 15 or newer, or x86_64 Linux. Linux means Ubuntu 24.04 with Claude Code, Codex CLI, Cursor CLI and Devin CLI, as far as its evidence goes.
  • Herdr 0.9 or newer, installed and running. Start your agent in a Herdr pane, so workers can open beside it.
  • A Rust toolchain (cargo) to install. Release archives exist but are unsigned and not notarized; see the unsigned distribution guide.
  • At least one worker CLI, installed and logged in, for example Claude Code

Install

# 1. The brgr CLI
cargo install --locked brgr-cli

# 2. Teach your agent how to use brgr
brgr integrate claude install    # Claude Code: installs the brgr skill
brgr integrate codex install     # Codex: installs the skill and session hooks
                                 # (Codex asks you to review them on its next start)

# 3. Register a worker. This runs one small prompt through it.
mkdir -p ~/brgr-scratch
brgr harness add "$(command -v claude)" --workspace ~/brgr-scratch --prompt "Reply with OK"
brgr doctor

On a terminal, brgr doctor starts with ok or one needs_attention line per problem. brgr doctor --json and a pipe keep the JSON, with a problems array. It is ready when "status" is "ok" and the worker you added shows "health": "healthy". Then start a new Claude Code or Codex session inside Herdr: an agent reads its skills when a session starts, so one that was already running does not know brgr yet.

The Herdr plugin adds a task board and workspace actions on top:

herdr plugin install justn-hyeok/brgr --ref v2.15.22

Use it

Inside Herdr, ask your agent in plain words, for example:

Use brgr to have two Claude Code workers review this diff, one for bugs and one for missing tests. Accept the results that hold up.

The agent runs commands like these, which you can also run yourself:

brgr run "Review this change" --harness local.claude-code --criterion "findings cite changed lines"
brgr result TASK
brgr accept TASK --reason "criteria verified"
brgr land TASK --workspace . --reason "criteria verified"   # code: check, accept, apply

Troubleshooting

You see What to do
could not find the calling Codex pane Start each brgr command from Codex with --as SESSION; the installed skill does this. brgr doctor shows under codex_trace whether your Codex release was checked.
A worker fails with "insufficient credits", a usage limit or an HTTP 4xx The worker's own account or model failed, not brgr. Use another harness, or pick a model with brgr config set model MODEL --harness local.claude-code.
a screen no brgr rule answers The error quotes the screen. Answer it with brgr input TASK --key KEY or --text TEXT, and open an issue so a rule can be added.
brgr doctor shows a harness as probe_evidence_changed Its CLI updated itself. Register it again with brgr harness add PATH --workspace ~/brgr-scratch --prompt "Reply with OK".
A failure note after every brgr command A failed run waits for you: inspect it with brgr result TASK, then brgr result TASK --ack.

Status

v2 is the current release line. Its author uses it daily on macOS, it has been run end to end on Linux but not used daily there, and it changes quickly; see the changelog. One check from its readiness record is still open: a full review of the code by someone other than the author. See the readiness status.

The execution model roadmap plans continuity foundations, Head Migration, and Dynamic Workflows while preserving the existing run contract.

brgr is written by AI coding agents under one maintainer's direction, so its code quality is not guaranteed; its behaviour is what the tests check. CONTRIBUTING.md says what that means and how to help.

The detailed contract, covering plugin internals, routes, pane mode, recursive workers, the completion loop and worktree cleanup, is in docs/guides/reference.md.