🎩 Mr. Overkill

"Refactoring is not a task. It's a lifestyle."

Mr. Overkill is an automated loop that forces Codex (the pedantic reviewer) and Claude (the tired developer) into a locked room. They will not stop refactoring your code until it is "perfectly over-engineered" or your API credit runs out.

⚠️ WARNING: FINANCIAL HAZARD

Do not run this script if you value your money.

This tool is designed to:

1. 🔥 Burn Tokens: It ignores "good enough" and strives for "unnecessarily complex."
2. 💸 Drain Wallets: Requires OpenAI (Paid) AND Anthropic (Pro/Max) simultaneously.
3. ♾️ Loop Forever: It might turn your "Hello World" into a Microservices Architecture.

Quick Install (If you dare)

# Install the package
pip install overkill          # or: uv tool install overkill / pipx install overkill

# As a project dependency (uv)
uv add overkill

# Upgrade
pip install --upgrade overkill
uv lock --upgrade-package overkill   # uv projects

# Initialize your project
overkill init /path/to/your-project

Or use the convenience script from the source repo:

git clone --depth 1 https://github.com/modocai/mr-overkill.git /tmp/overkill \
  && /tmp/overkill/install.sh /path/to/your-project \
  && rm -rf /tmp/overkill

🛠️ Prerequisites (The "Rich Dev" Starter Pack)

You need these to participate in the madness:

Accounts (yes, you need all three — that's the point):

• OpenAI account (paid plan) — because free tier is for weak code
• Anthropic account (Pro/Max plan or API credits) — because Claude needs to think deeply about your variable names
• Google AI account (API key) — because Gemini wants in on the overkill too

Runtime:

• Python 3.11+ — for the overkill CLI
• Node.js v18+ — Codex and Claude Code CLI are npm packages, so yes, you need this
• A fast credit card — essential

CLI Tools:

npm install -g @openai/codex             # Codex CLI
npm install -g @anthropic-ai/claude-code  # Claude Code CLI
npm install -g @google/gemini-cli         # Gemini CLI

• jq — JSON processor
• gh — GitHub CLI (optional, for PR comments)
• envsubst — part of GNU gettext (macOS: brew install gettext)
• perl — used for JSON extraction and deduplication (pre-installed on macOS and most Linux)
• git

Quick Start

# In your project directory (after install):

# Review loop — review and fix diffs against target branch
overkill review-loop -n 3

# Refactor suggest — analyze full codebase for refactoring opportunities
overkill refactor-suggest -n 1 --dry-run

Usage: overkill review-loop

overkill review-loop [OPTIONS]

Options:
  -t, --target <rev>       Target to diff against (default: develop). Accepts any
                           git revision, not just a branch name: a SHA, a tag, or
                           HEAD~5 all work, so you can review "everything since
                           commit X" without opening a PR. A revision that moves
                           with HEAD is pinned to a SHA when the run starts, so
                           the loop's own fix commits cannot shrink the range.
  --commit <rev>           Review an already-merged commit instead of the branch
                           diff. Creates a review/<sha>-<ts> branch off HEAD and
                           applies fixes there; no PR is created. <rev> is a single
                           commit — ranges are not supported. Excludes -t.
  --push                   Push the auto-created review branch (default: local only)
  --wip                    Include uncommitted working-tree changes in the review.
                           With commits enabled they are parked in a scaffolding
                           commit that is unwound when the run finishes, so no
                           commit is left behind either way. Excludes --commit.
  -n, --max-loop <N>       Maximum review-fix iterations (required, unless --resume)
  --max-subloop <N>        Maximum self-review sub-iterations per fix (default: 4)
  --no-self-review         Disable self-review (equivalent to --max-subloop 0)
  --dry-run                Run review only, do not fix
  --no-auto-commit         Fix but do not commit/push (single iteration)
  --resume                 Resume from a previously interrupted run (reuses existing logs)
  --fix-nits               Also flag nits and style issues during self-review
  --context <text>         Additional context for the reviewer (design intent,
                           constraints)
  --reviewer <be[,be]>     Reviewer backend(s): claude|codex|gemini|agy
                           (default: codex)
  --fixer-backend <be>     Fixer backend: claude|codex|gemini|agy (default: claude)
  --self-reviewer-backend <be>  Self-review backend (default: same as fixer)
  --ci-trigger-mode <m>    CI trigger policy: every|last-only|none (default: last-only).
                           'last-only' tags each iteration commit with [skip ci]
                           and pushes a single empty trigger commit on PASS —
                           CI runs once instead of once per iteration.
                           Use 'every' to restore pre-0.3 per-commit CI.
  --diagnostic-log         Save full Claude event stream to sidecar files
  --no-budget-gate         Skip token-budget checks and run regardless
                           (same as OVERKILL_SKIP_BUDGET=1)

Examples:
  overkill review-loop -t main -n 3          # diff against main, max 3 loops
  overkill review-loop -n 5                  # diff against develop, max 5 loops
  overkill review-loop -n 1 --dry-run        # single review, no fixes
  overkill review-loop -n 3 --no-self-review # disable self-review sub-loop
  overkill review-loop --resume              # resume an interrupted run
  overkill review-loop -n 2 --reviewer claude  # use Claude as reviewer
  overkill review-loop -n 2 --reviewer codex,gemini  # parallel reviewers
  overkill review-loop -n 10 --ci-trigger-mode last-only  # CI fires once on PASS

  # Review only what landed after a given commit, before opening a PR
  overkill review-loop -t abc123 -n 3
  overkill review-loop -t "$(git merge-base origin/develop HEAD)" -n 3

  # Improve a commit that is already merged
  overkill review-loop --commit abc123 -n 1 --dry-run   # report only, no branch
  overkill review-loop --commit abc123 -n 3             # fix on a review/* branch

  # Review work you have not committed yet
  overkill review-loop --wip -n 1 --dry-run   # report only, nothing touched
  overkill review-loop --wip -n 3             # fix it, still uncommitted at the end

Reviewing an already-merged commit

--commit exists for the case the branch diff cannot express: a change that already landed, which you now want to improve.

1. The commit's diff is written to .overkill/logs/scope.diff. It is computed against the commit's first parent, so merge commits produce a real patch — git show prints nothing for those.
2. A review/<sha>-<timestamp> branch is created off your current HEAD and the fixes are committed there. The branch stays local unless you pass --push, and no PR is created or commented on.
3. The reviewer treats scope.diff as scope only. Since other commits may have landed since, it must confirm each finding against the file's current contents and cite current line numbers.

Run it from a clean, up-to-date checkout of the branch the commit lives on:

git switch main && git pull
overkill review-loop --commit abc123 -n 3

After upgrading, re-run overkill init in each repo — --commit and --wip need the ${REVIEW_SCOPE_NOTE} marker that the refreshed review prompts carry, and the run aborts with an explanatory error if it is missing. Note that init overwrites .overkill/prompts/active/, so back up any customised prompts first.

Reviewing work you have not committed yet

Without --wip the review scope is git diff <target>...<current> — committed work only. A dirty tree is rejected outright, and under --dry-run it is silently left out of scope. --wip pulls it in.

How it gets there depends on whether the run is allowed to commit:

Both paths end the same way: your working tree is dirty again, with the fixes applied on top of your own edits. Only the iteration count differs. Multiple iterations need commits because the loop detects convergence from the commit graph, so --wip parks your work in a throwaway commit, lets the loop run against it unchanged, and then removes the scaffolding with git reset --mixed.

overkill review-loop --wip -n 3
git diff                              # your work plus the fixes, uncommitted
cat .overkill/logs/wip-fixes.diff     # just what the loop changed

Worth knowing before you use it:

• Nothing is ever pushed in --wip mode, and no PR is commented on. This is not configurable — the scaffolding commit holds unfinished work.
• git add -A sweeps in anything .gitignore does not cover. The file list is printed before the scaffolding commit is made. Nothing is pushed and the commit is unwound, but check the list if you keep untracked secrets around.
• A staged/unstaged split does not survive. git reset --mixed leaves everything unstaged.
• If the run is interrupted the scaffolding stays. The command to undo it is printed at the start and the base commit is saved to .overkill/logs/wip-base.txt; --wip --resume picks an interrupted run back up, parking the work again if the scaffolding is already gone. A run that already finished is left alone. Resume needs commits enabled — the other two modes are a single pass with nothing to resume. A fresh --wip run refuses to start on top of leftover scaffolding rather than nest a second commit on it, which would strand the earlier draft on the branch — including when the scaffolding sits behind fix commits the interrupted run already made. A resume refuses too if you have committed normally on top of it, because unwinding would rewind that commit into uncommitted changes.
• A resumed run's wip-fixes.diff only covers the iterations after the resume. Re-parking folds the earlier attempt's fixes in with your own work, so they cannot be told apart again; that attempt's diff is kept beside it as wip-fixes-<sha>.diff.
• Commit hooks are skipped for the run's own commits. Work in progress routinely fails hooks it will pass once finished, and every commit --wip makes is torn down again.
• An unfinished merge, rebase, cherry-pick or revert blocks the mode. The scaffolding commit would conclude the operation, and unwinding would then reset past it.
• New files are included. They are staged as intent-to-add so the reviewer can see them, then unstaged again.

Usage: overkill refactor-suggest

Unlike review-loop which reviews diffs, refactor-suggest analyzes the entire codebase for refactoring opportunities at a chosen scope level.

overkill refactor-suggest [OPTIONS]

Options:
  --scope <scope>          Refactoring scope: auto|micro|module|layer|full (default: auto)
  -t, --target <branch>    Target branch to base from (default: develop)
  -n, --max-loop <N>       Maximum analysis-fix iterations (default: 1)
  --max-subloop <N>        Maximum self-review sub-iterations per fix (default: 4)
  --no-self-review         Disable self-review (equivalent to --max-subloop 0)
  --dry-run                Run analysis only, do not apply fixes
  --no-dry-run             Force fixes even if .refactorsuggestrc sets DRY_RUN=true
  --auto-approve           Skip interactive confirmation for layer/full scope
  --create-pr              Create a draft PR after completing all iterations
  --resume                 Resume from a previously interrupted run (reuses existing logs)
  --with-review            Run review-loop after PR creation (default: 4 iterations)
  --with-review-loops <N>  Set review-loop iteration count (implies --with-review)
  --reviewer <be[,be]>     Reviewer backend(s): claude|codex|gemini|agy
                           (default: codex)
  --fixer-backend <be>     Fixer backend: claude|codex|gemini|agy (default: claude)
  --self-reviewer-backend <be>  Self-review backend (default: same as fixer)
  --diagnostic-log         Save full Claude event stream to sidecar files
  --no-budget-gate         Skip token-budget checks and run regardless
                           (same as OVERKILL_SKIP_BUDGET=1)

Examples:
  overkill refactor-suggest -n 3                             # auto scope (budget-aware)
  overkill refactor-suggest --scope micro -n 3               # function/file-level fixes
  overkill refactor-suggest --scope module -n 2 --dry-run    # analyze module duplication
  overkill refactor-suggest --scope layer -n 1 --auto-approve  # cross-cutting concerns
  overkill refactor-suggest --scope full -n 1 --create-pr    # architecture redesign + PR
  overkill refactor-suggest -n 2 --with-review               # auto scope + auto review
  overkill refactor-suggest --scope module -n 3 --with-review-loops 6 # custom review
  overkill refactor-suggest -n 1 --reviewer codex,claude  # parallel analysis

Usage: overkill init

Initialize .overkill/ in a project directory. Safe to re-run — prompts are refreshed, user-edited configs are preserved.

overkill init [TARGET_DIR]   # default: current directory

Creates:

.overkill/
├── prompts/active/          # 10 prompt templates
├── .overkillrc              # review-loop config
├── .refactorsuggestrc       # refactor-suggest config
├── logs/                    # runtime logs
│   └── refactor/            # refactor-suggest logs
└── .install-manifest        # tracks tool-owned files

Scopes

How refactor-suggest works

1. Collect source file list (git ls-files)
2. Reviewer(s) analyze the full codebase for scope-specific refactoring opportunities
3. (layer/full) Display refactoring plan and wait for confirmation
4. The selected fixer applies refactoring (two-step: opinion → execute)
5. The selected self-reviewer checks changes, re-fixes if needed
6. Auto-commit & push to refactoring branch
7. Repeat until clean or max iterations reached
8. (--create-pr) Create draft PR
9. (--with-review) Run review-loop on the new PR

Recommended workflow: start with --dry-run to review findings, then re-run without it to apply.

Configuration

After running overkill init, config files live in .overkill/:

.overkill/.overkillrc

TARGET_BRANCH="main"
MAX_LOOP=5
MAX_SUBLOOP=4
AUTO_COMMIT=true
REVIEWER_BACKEND="codex"    # comma list: claude | codex | gemini | agy
FIXER_BACKEND="claude"      # claude | codex | gemini | agy
# SELF_REVIEWER_BACKEND="gemini"  # omitted: follows FIXER_BACKEND
PROMPTS_DIR="./custom-prompts"

See .overkill/.overkillrc for all available options.

.overkill/.refactorsuggestrc

SCOPE="auto"
TARGET_BRANCH="develop"
MAX_LOOP=3
MAX_SUBLOOP=4
# DRY_RUN: safe default — remove to apply fixes (script default: false)
DRY_RUN=true
AUTO_APPROVE=false
CREATE_PR=false
WITH_REVIEW=false
REVIEW_LOOPS=4
REVIEWER_BACKEND="codex"    # comma list: claude | codex | gemini | agy
FIXER_BACKEND="claude"      # claude | codex | gemini | agy
# SELF_REVIEWER_BACKEND="gemini"  # omitted: follows FIXER_BACKEND
PROMPTS_DIR="./custom-prompts"

How review-loop works

1. Check prerequisites (git, codex, claude, jq, envsubst, target branch)
2. Create .overkill/logs/ directory
3. Loop (iteration 1..N):
   a. Generate diff: git diff $TARGET...$CURRENT
   b. Empty diff → exit
   c. Reviewer(s), via --reviewer, review the diff → JSON with findings
   d. No findings + "patch is correct" → exit
   e. The selected fixer fixes all issues (P0-P3)
   f. Sub-loop (1..MAX_SUBLOOP):
      - The selected self-reviewer checks the uncommitted fixes (git diff)
      - If clean → break
      - The selected fixer re-fixes based on self-review findings
   g. Auto-commit all fixes + re-fixes to branch
   h. Push to remote (updates PR)
   i. Post review/fix/self-review summary as PR comment
   j. Next iteration reviews the updated committed state
4. Write summary to .overkill/logs/summary.md

Output Files

All logs are git-ignored by default (inside .overkill/).

review-loop logs (.overkill/logs/)

refactor-suggest logs (.overkill/logs/refactor/)

Token Budget Checker

The budget checker verifies Claude Code's 5-hour rate limit before starting expensive loops.

Codex is checked too, but only when it authenticates through a ChatGPT plan. Auth mode is read from $CODEX_HOME/auth.json (default ~/.codex/auth.json), falling back to the login method in config.toml when Codex keeps credentials in the OS keyring instead; under API-key auth there are no plan rate-limit windows, so the gate is skipped entirely and stale session logs from a previous plan login are ignored.

How it estimates usage

Tier detection reads rateLimitTier from ~/.claude/telemetry/*.json (field event_data.user_attributes). Mapping: default → pro, default_claude_max_5x → max5, default_claude_max_20x → max20.

Scope thresholds

Go/no-go decision based on current usage percentage:

Bypassing the gate

Budget data is an estimate read from local CLI logs, so it can be wrong — stale logs, a changed auth mode, or a new rate-limit payload shape. To run anyway:

overkill review-loop -n 3 --no-budget-gate   # per run
OVERKILL_SKIP_BUDGET=1 overkill review-loop -n 3   # env var, covers every gate

NO_BUDGET_GATE=true in .overkillrc / .refactorsuggestrc makes it the default.

Customizing Prompts

Edit the templates in .overkill/prompts/active/.

review-loop prompts

• codex-review.prompt.md — Review prompt sent to Codex. Uses variables: ${CURRENT_BRANCH}, ${TARGET_BRANCH}, ${ITERATION}.
• claude-review.prompt.md — Review prompt for Claude reviewer (symlink to codex-review by default).
• claude-fix.prompt.md — Opinion prompt: Claude evaluates review findings. Uses: ${REVIEW_JSON}, ${CURRENT_BRANCH}, ${TARGET_BRANCH}.
• claude-fix-execute.prompt.md — Execute prompt: tells Claude to fix based on its opinion.
• claude-self-review.prompt.md — Self-review prompt for Claude to check its own fixes. Uses: ${REVIEW_JSON}, ${CURRENT_BRANCH}, ${TARGET_BRANCH}, ${ITERATION}.

refactor-suggest prompts

Each scope has a dedicated prompt with scope-specific instructions, anti-pattern guardrails, and good/bad finding examples:

• codex-refactor-{micro,module,layer,full}.prompt.md — Codex reviewer prompts per scope.
• claude-refactor-{micro,module,layer,full}.prompt.md — Claude reviewer prompts (symlinks to codex versions by default).

All refactor prompts use variables: ${TARGET_BRANCH}, ${ITERATION}, ${SOURCE_FILES_PATH}.

• claude-refactor-fix.prompt.md — Opinion prompt: Claude evaluates refactoring findings with scope-aware judgment. Uses: ${REVIEW_JSON}, ${CURRENT_BRANCH}, ${TARGET_BRANCH}.
• claude-refactor-fix-execute.prompt.md — Execute prompt with safety guards (syntax check, scope overflow detection, regression testing).

Reference prompts (read-only originals) are in prompts/reference/.

Priority Levels

Exit Conditions

The loop terminates when any of these occur:

• all_clear — No findings and overall verdict is "patch is correct"
• no_diff — No changes between branches
• dry_run — Review-only mode
• max_iterations_reached — Hit the -n limit
• auto_commit_disabled — --no-auto-commit or AUTO_COMMIT=false; fixes applied but not committed
• parse_error — Could not parse Codex output as JSON

Uninstall

# Quick — just nuke the directory
rm -rf .overkill

# Also remove the Python package
pip uninstall overkill       # or: uv tool uninstall overkill / pipx uninstall overkill

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-feature)
3. Commit your changes
4. Open a Pull Request against develop
5. Run overkill review-loop -n 3 --dry-run on your PR branch — required. Let Mr. Overkill review your code before a human ever sees it.

Development

git clone https://github.com/modocai/mr-overkill.git
cd mr-overkill
uv sync                      # install dev dependencies
uv run pytest                # run tests
uv run ruff check src/ tests/
uv run mypy src/

Testing

uv run pytest --tb=short

License

MIT © 2026 ModocAI

Selecting role backends

Both review-loop and refactor-suggest accept independent reviewer and fixer backends. --reviewer selects one or more review backends; --reviewer-backend remains a compatible alias. The rc key REVIEWER_BACKEND is unchanged. Defaults remain Codex review and Claude fix. Self-review follows the fixer unless --self-reviewer-backend / SELF_REVIEWER_BACKEND is set.

overkill review-loop -n 3 --reviewer gemini --fixer-backend codex
overkill review-loop -n 3 --reviewer codex,claude,gemini
# Optional independent verification of the fix:
overkill review-loop -n 3 --fixer-backend codex --self-reviewer-backend claude

Reviewer lists are comma-separated, whitespace is ignored, and duplicates are collapsed while preserving the first occurrence. When multiple reviewers are selected, they run in parallel once per iteration. Their findings are combined into a single review for the normal fixer path, and all selected reviewers must succeed before fixing begins. Exact duplicate findings are collapsed only by exact match; Mr. Overkill does not semantically merge similar findings. Each individual review is written to reviewers/<backend>/review-N.json, while the combined result remains review-N.json. The fixer and self-reviewer behavior is unchanged.

Install and authenticate each selected CLI before running. Codex fixes use workspace-write; Gemini fixes use sandboxed yolo mode. Opinion and self-review use Codex read-only or Gemini plan mode (requires a Gemini CLI supporting that mode). Claude retains its existing two-step session. Codex and Gemini receive the opinion and original findings explicitly in the editing step. Existing claude-*-fix* and claude-self-review prompt filenames remain shared templates for compatibility with custom prompt directories.

Gemini reviewers (including refactoring analysis) also use sandboxed plan mode, never yolo. Overkill supplies the requested diff directly because plan mode may disable shell tools; commit/WIP scope remains authoritative. The bundled Gemini prompts include evidence-driven review guidance without invoking an installed /code-review command, changing the target to origin/HEAD, or replacing the JSON/P0-P3 contract. Refresh existing local prompt copies with overkill init after inspecting any customizations. Permission failures are not code defects; there is no automatic fallback to editing mode.

Plan mode is a CLI permission policy, not a guarantee against every possible side effect (for example, Gemini permits its own plan-directory writes). See docs/gemini-review-guidance.md for provenance, headless verification limits, and the reproducible prompt benchmark.

Gemini will not run headless in a folder it does not trust, and inside its sandbox it cannot read your trust list (~/.gemini/trustedFolders.json). Overkill reads that list itself and passes GEMINI_CLI_TRUST_WORKSPACE=true into the sandbox only for folders you have already trusted — trust one by running gemini in it once. An explicit GEMINI_CLI_TRUST_WORKSPACE or GEMINI_RESTRICTED_MODE in your environment is left as you set it.

CLI options override rc settings. --resume restores saved role selections unless explicitly overridden on the command line; an inherited self-review selection continues to follow the fixer. --no-self-review still disables this stage.

Antigravity CLI is supported explicitly as agy for all three roles:

overkill review-loop -n 3 --reviewer agy --fixer-backend codex
overkill refactor-suggest --scope module --fixer-backend agy

Google announced the consumer transition from Gemini CLI on May 19, 2026, with free/Pro/Ultra access ending June 18; enterprise and paid API-key access remain. See the official announcement. Existing gemini selections continue to invoke gemini; no automatic executable or account switching occurs. Authenticate agy separately before use.

Antigravity uses --mode plan for review/opinion and --mode accept-edits for fixes, with --sandbox in both. It does not bypass permissions: shell commands may be denied in headless mode unless your Antigravity policy permits them. Use an up-to-date CLI that applies --mode to headless runs. Antigravity shares the existing gemini-* review prompts. Local Antigravity quota preflight data is not available; runtime errors go through the retry/error handling path. See headless mode and execution modes.