Git bisect assistant: find the commit that broke it, safely

What it does

Finds the commit that broke something by walking the history automatically.

• Runs git bisect run with your test command (exit 0 = good, non-zero = bad, 125 = cannot test / skip)
• If no good ref is given, suggests one automatically: the latest reachable tag or the merge-base with main/master
• Before bisecting, checks that the command passes on good and fails on bad, and stops if the test does not reproduce the bug
• Logs every step (commit, exit code, verdict, seconds) to a JSONL file
• Per-run timeout that kills the whole process tree, counted as skip or bad as you choose
• Always runs git bisect reset back to the original branch, also on errors and Ctrl+C
• Reports the first bad commit with author, date, subject and diff stat

How to use

python scripts/bisect_run.py --detect-only
python scripts/bisect_run.py --cmd "python -m pytest tests/test_cart.py -q" --good v1.4.0 --timeout 300

Ask the agent something like "this test passed in v1.4, find the commit that broke it". It chooses the command, runs the bisect and explains the likely cause. Works with Claude, Codex, Hermes Agent and Cursor.

Requirements

• Python 3 (standard library only)
• Git

Caveats

• It will not start when tracked files have uncommitted changes or a bisect is already running, and it never stashes on its own.
• It never commits, pushes or deletes files, but your test command runs on many old commits, so do not use commands that touch production systems.
• Flaky tests can make bisect point at the wrong commit.
• On Windows the command runs through cmd.exe, so use double quotes.