muse bisect — binary search for regressions

muse bisect is a regression-hunting power tool for humans and agents alike. Given a commit where a bug first appears (bad) and a commit where it was not present (good), it performs a binary search through the history between them — cutting the search space in half at each step — until the exact commit that introduced the bug is isolated.

For a 1,000-commit range, muse bisect needs at most 10 steps. For 1,000,000, it needs 20.

Subcommands

Manual workflow

# 1. Start the session with the bad and good bounds:
muse bisect start --bad HEAD --good v1.0.0

# 2. Muse suggests a midpoint:
# Next to test: a1b2c3d4ef56  (32 remaining, ~5 steps left)

# 3. Test that commit and report the result:
muse bisect good    # or: muse bisect bad

# 4. Repeat until the first bad commit is found:
# ✅ First bad commit found: deadbeef1234…
# Run 'muse bisect reset' to end the session.

# 5. Clean up:
muse bisect reset

Automated workflow (muse bisect run)

The run subcommand fully automates the search. The command you provide is run at each bisect step; the exit code determines the verdict:

muse bisect start --bad HEAD --good v1.0.0
muse bisect run "pytest tests/test_regression.py -x -q"

Muse will automatically advance until the first bad commit is found.

State file

The bisect session is stored at .muse/BISECT_STATE.toml:

bad_id = "deadbeef…"
good_ids = ["aabbccdd…"]
skipped_ids = []
remaining = ["a1b2c3…", "d4e5f6…", …]
log = ["deadbeef… bad 2026-03-19T14:22:01+00:00", …]
branch = "main"

The state file is rebuilt at every step so it survives interruptions.

Multiple good commits

You can specify multiple --good bounds to narrow the search range from multiple known-good ancestors:

muse bisect start --bad HEAD --good v1.0.0 --good v1.1.0 --good v1.2.0

Agent workflow

# Fully autonomous regression hunt:
muse bisect start --bad HEAD --good "$LAST_GREEN_CI_COMMIT"
muse bisect run "./ci/test.sh"
# Agent reads the result and files a bug report with the first-bad commit.

Exit codes

Interaction with other commands

• muse bisect operates on existing commits in the store — it does not check out files automatically. For file-level testing, use muse bisect run with a script that reads state/ directly.
• After muse bisect reset, all bisect state is removed and the normal branch workflow resumes.