🦝 Bumfuzzle: Starting Point for Every Project

[!CAUTION] Now you can bash the soul out of your coding agent. And it will never break a rule again.

Summary

• bumfuzzle is a single self-contained HTML file served by a lightweight local Python server. It shuts down when you close the tab. Nothing leaves your machine.
• .bumfuzzle/config.yml is the only config file created in your project. One file, all rules.
• bumfuzzle run runs every check marked enabled in .bumfuzzle/config.yml. Create that file first with bumfuzzle init.

Working with AI coding agents

It works perfectly with Cursor, Claude Code, Codex, and many more.

Models: Opus 4.8, Sonnet 5, Fable 5, GPT 5.5, GLM 5.2, and many more.

When a check fails, bumfuzzle run prints exactly what broke and how to fix it. The agent reads the hint, resolves the issue, and reruns, in a loop, until the board is clean.

Table of contents

• Features
• Install
• How to use
• Roadmap
• Comparison
• Contributing

Features

• Closes the agentic verification loop: custom instructions tell the model exactly what to do next.
• Extremely fast, ridiculously simple, and lightweight: zero external dependencies.
• Works with any language, any OS, any project: from a personal website to the Linux kernel.
• You pick the rules yourself: linters, hooks, and virtually anything else.
• One config to rule them all: a single .bumfuzzle/config.yml stores every configuration.
• One entry point for every check: the bumfuzzle command runs it all.
• Visual Wizard: set up every check you want in seconds.
• Zero prod footprint: Bumfuzzle is never included in your build.
• Batteries included: ships with most of the common presets, so you just pick what you need.

Install

Every command below works identically as bumfuzzle or bf — bf is just a shorter convenience alias for the same binary.

| Method | Summary | Installation | Usage | |---|---|---|---| | Homebrew | Global install, adds bumfuzzle/bf to PATH system-wide | brew install arc-com/tools/bumfuzzle | bf run | | npm | JS/TS projects using npm; installs as a dev dependency | npm install -D bumfuzzle | bf run | | pnpm | JS/TS projects using pnpm; installs as a dev dependency | pnpm add -D bumfuzzle | pnpm exec bf run | | yarn | JS/TS projects using yarn; installs as a dev dependency | yarn add -D bumfuzzle | yarn bf run | | pip | Python projects; installs into the active environment | pip install bumfuzzle | bf run | | uv | Python projects using uv; installs as a dev dependency | uv add --dev bumfuzzle | uv run bf run | | poetry | Python projects using poetry; installs as a dev-group dependency | poetry add --group dev bumfuzzle | poetry run bf run | | From source | Clone directly and install scripts | git clone https://github.com/arc-com/bumfuzzle && ./bumfuzzle/scripts/install.sh | bf run |

Installing from source adds bumfuzzle and bf to ~/.local/bin. Run scripts/uninstall.sh to remove them.

How to use

cd my-project

bumfuzzle init             # writes .bumfuzzle/config.yml from the template

bumfuzzle wizard
# opens web wizard in browser
# configure checks, environments, stacks, rules; autosaves as you edit

# Every subsequent run
bumfuzzle run              # run every check marked enabled in .bumfuzzle/config.yml
bumfuzzle run --verbose    # show passing checks too

Manage your rules two ways: run bumfuzzle for the visual wizard, or edit .bumfuzzle/config.yml directly. bumfuzzle run never takes a target — it runs whatever is enabled. A check may self-label readonly: true in .bumfuzzle/config.yml as a hint to whoever's reading the config; the framework doesn't verify or enforce it.

Roadmap

Bug fixes

• [ ] Fix drag-and-drop crash when dropping a rule into an empty group

Planned improvements

• [ ] Standardize argument-passing and argument-expectation conventions across shared scripts
• [ ] Support user-defined arguments in custom command_checks scripts
• [ ] Reduce .bumfuzzle/config.yml size by extracting reusable rule sets into importable modules

Comparison

How Bumfuzzle compares to other tools in the AI-agent-guardrail space:

| | Bumfuzzle | agentlint | agent-governance-toolkit | drift-guard | Plain pre-commit | |---|---|---|---|---|---| | Enforcement point | Git commit (pre-commit hook) | Real-time, tool-call time | Git commit (hook templates) | Git commit / CLI | Git commit | | Config format | Single .bumfuzzle/config.yml | Rule packs (JS/JSON config) | Docs + hook templates, no single schema | Zero-config | .pre-commit-config.yaml + per-hook config | | Structural checks (files, dirs, env drift) | ✅ built-in | Partial (code-quality/security focus) | Governance/process focus, not file structure | Design/UI drift only | Only if you write custom hooks | | Visual setup wizard | ✅ | ❌ | ❌ | ❌ | ❌ | | Zero prod footprint | ✅ (dev dependency only) | ✅ | ✅ (docs/process, not shipped) | ✅ | ✅ |

Comparisons above reflect public information about these projects as of July 2026 and may not capture every capability. Verify directly with each project before relying on this table.

Contributing

Open an issue: github.com/arc-com/bumfuzzle/issues