Getting started

Install once. Run it inside any project.

BuildBrake uses the folder where you start it as the project boundary. Receipts and local state stay in that project.

Platform support

Supported platforms
macOS	Supported	Tested in CI and during development.
Linux	Supported	Tested in CI.
Windows with WSL2	Supported path	Run BuildBrake and the project inside WSL2.
Native Windows	Not supported	v0.1 requires a Unix environment.

Requirements

Python 3.9 or newer
Git
Codex CLI, signed in with your own account

Install

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex
git clone https://github.com/karangandhidev/buildbrake.git
cd buildbrake
./install.sh
bb doctor

bb doctor checks Python, Git, Codex, and Codex sign-in. If something is missing, it prints a copy-friendly fix.

Start the dashboard

cd /path/to/your/project
bb serve

The dashboard opens at http://127.0.0.1:8765. It identifies the current folder so you know which project BuildBrake will inspect and modify.

Run your first task

Use a clean Git branch.
Enter one observable task under What should the agent do?
Leave task size on Auto.
Click Check and save, then Run task.
Inspect the Git diff and the BuildBrake receipt.

Example task

Change the README installation heading to “Install locally” and verify that the rest of the README is unchanged.

Update BuildBrake

To update an existing installation, run these commands inside your original BuildBrake clone, then restart any running dashboard:

git pull --ff-only
./install.sh
bb doctor

Troubleshooting

The terminal cannot find bb

Use the absolute command printed by the installer, or add its command directory to your shell PATH. Open a new terminal after saving a PATH change. Run bb doctor to check the installation.

Changes do not appear in the dashboard

A normal installation uses an installed copy of BuildBrake. Editing the cloned source does not update that copy. For development, run ./install.sh --editable once inside the clone. Refresh the browser after HTML changes and restart bb serve after Python changes.

A completed task is not marked proved

Completion means the agent stopped. Check the receipt for a failed verification command or an unresolved target. A visual or usability result may need human review even when tests pass. Review the changes, then record your outcome and reason in the dashboard.

The wrong project appears

Stop the dashboard, change to the intended project folder, and run bb serve again. Confirm the folder displayed above the task form before starting work.

Uninstall

The default installation lives under ~/.local/share/buildbrake. Command links live in ~/.local/bin, or /opt/homebrew/bin when writable. Remove those links and the isolated directory to uninstall it.