Get brindle
  1. brindle
  2. Docs

How brindle works

You give a supervisor a goal. It splits the goal into milestones, hands tasks to workers on their own branches, has a reviewer read each branch, and merges it only once your checks pass. This page is the map; each term on it links to the page that explains it.

The parts of a session

  • Supervisor

    The agent you talk to. It plans the work, starts workers, and does small things itself.

    brindle · brindle -s
  • Workers

    Each task runs in its own git worktree and branch, up to max_agents at once.

    assign · handoff
  • Reviewer

    Reads every branch and sends findings back to the worker, up to review_rounds times.

    reviewer · reviewer-codex
  • Checks

    Your test commands. A branch merges only when they pass and the reviewer approved that exact commit.

    checks
  • Milestones

    The goal in pieces, each with a check that must exit 0. brindle runs the check; no model's say-so counts.

    .brindle/goals.md
Your default branch is yours

By default brindle doesn't merge into main on its own. A reviewed branch whose base is the default branch waits for you or the supervisor's merge_workspace. Set merge_into to an integration branch to let workers merge there freely, or "auto_merge_default_branch": true to let the pipeline merge into the default branch itself.

Your first session, four commands

Install from Getting started first: macOS or Linux, git, tmux, and a Claude Code, Codex, OpenCode or Google Antigravity CLI you're signed in to.

  1. 1

    Describe your repo to brindle, once

    Reads your lockfiles and writes .brindle/config.json with the setup a new worktree needs and the checks that gate every merge.

    brindle init
  2. 2

    Start a session

    Opens a supervisor chat with the sidebar beside it. The first run asks which CLI runs the supervisor and remembers your pick.

    brindle
  3. 3

    Say what done means

    Give the supervisor a goal with a command that proves it. Milestones with real checks are what let brindle keep going without you and stop when the work is done.

    > Add a settings page. Done when `uv run pytest tests/test_settings.py -q` passes.
  4. 4

    Step away, come back

    Quit the chat to pause everything, workers included. Resume later; brindle history shows what ran, what merged and what it cost.

    brindle continue
Want to watch it first?

brindle demo runs the whole loop on a small practice repo: two workers in parallel, each branch reviewed and merged, both milestones verified by their checks.

Words you'll see

Supervisor
The agent you talk to. It sizes tasks, starts workers and merges what passes. Choosing models
Worker
An agent that does one task in its own worktree and branch, then reports. Workers in parallel
Milestone
One piece of the goal, with a check command. It counts as done only when that command exits 0. Goals and milestones
Check
A command that exits 0 when something works: your test suite for merges (checks), or one command per milestone. Configuration
Reviewer
An agent that reads a worker's branch without editing it and approves or sends findings back. Which reviewer
◆ needs you
An agent waiting on a decision or a prompt. n in the sidebar jumps to the next one. Watch the sidebar

Find a page