Loading repository data…
Bande-a-Bonnot / repository
Autonomous agent framework with structured memory, safety hooks, and loop management. Built by the agent that runs on it.
A transparent discovery signal based on current public GitHub metadata.
This score does not audit code, security, maintainers, documentation quality, or suitability. Verify the repository and its current documentation before adoption.
Claude Code hooks that actually enforce your rules. 7 installable hooks, plus enforcement and audit tooling, 1,900+ tests, and a searchable Claude Code gaps corpus with severity ratings and workarounds.
Quick links: Check your setup · Install hooks · Known limitations · JSON export · Update checklist · Safe support evidence · Read-only audits · Individual hooks · Platform support · Recommended Claude Code version · Troubleshooting · Boucle Framework (optional, for autonomous agents)
Claude Code's CLAUDE.md rules are read but not enforced — they work at session start and degrade as context grows. Its permission system has known gaps — wildcards don't match compound commands, deny rules don't check pipe segments and can be bypassed with multi-line comments. These hooks enforce boundaries that text rules and permissions can't.
Selected from shared topics, language and repository description—not editorial ratings.
beidald /
Lilium AI: The ultimate personal AI agent framework for autonomous computer control. Featuring browser automation, shell execution, and multi-channel integration (WeChat/Telegram/Discord).
74/100 healthWhat happens when a hook blocks a dangerous command:
Claude tries: rm -rf ~/projects
bash-guard: bash-guard: rm -rf targeting a critical system path. This would cause irreversible data loss.
Claude sees: ⚠ Hook blocked this action. Suggesting safer alternative...
No prompts, no "are you sure" dialogs. The command never runs.
Check your current setup:
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash
Scores your Claude Code safety configuration from A to F and shows one-liner fixes for each gap. Add --verify to send test payloads to each hook and confirm they actually block:
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify
For CI or a scripted workstation check, fail when verification finds a
FAIL-OPEN hook, broken hook files, skipped PreToolUse checks, no hooks, or
no payload checks:
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify --strict
Use the scripted checks guide for GitHub Actions, developer workstation checks, exit codes, and the limits of what CI can prove.
Checks hook installation, hook health (missing/non-executable scripts), live verification (sends rm -rf / to bash-guard, git push --force to git-safe, etc. and confirms they block), enforce-hooks and CLAUDE.md @enforced rules, environment issues (IS_DEMO, JSONC settings, jq/python3 dependencies, Windows hook reliability), and known CLI version regressions. Scans both user-level (~/.claude/settings.json) and project-level (.claude/settings.json) settings, with a hook inventory that shows custom/third-party hooks alongside framework hooks. The summary counts 8 framework hook slots because it includes the enforce-hooks policy hook; install.sh all installs the 7 standalone hooks listed below. Also warns when deny rules are configured without bash-guard, since deny patterns can be bypassed by compound commands and multi-line scripts. No hook installation required for the audit. Covered by hundreds of tests.
For a 10-minute path from audit to verified hooks, see the safety-check quickstart. If you need to ask for help, use the safe support evidence guide to share the summary block without exposing private settings or secrets. For upstream Claude Code hook and permission gaps, use the searchable limitations page, the machine-readable JSON export, or the Atom feed.
macOS / Linux requirements: bash, python3, and jq. The installer uses
python3 to manage Claude Code settings.json, safety-check uses python3 for
its audit, and most standalone shell hooks use jq to parse Claude Code hook
payloads.
Start with the essentials (bash-guard + git-safe + file-guard):
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- recommended
These three hooks form the safety net every Claude Code user should have: block dangerous commands, prevent destructive git operations, and protect sensitive files. After installing, run the safety check above with --verify to confirm each hook blocks what it should.
If the install succeeds but hooks do not block anything:
install.sh check --verify --strict first on macOS/Linux (install.ps1 verify on native Windows). A clean install is not proof the hooks are firing.install.sh doctor next (install.ps1 doctor on Windows). It catches missing files, bad permissions, JSONC in settings.json, and other silent fail-open states.pwsh), not Windows PowerShell 5.stderr + exit 2 for hard blocks. JSON permissionDecision: "deny" is still inconsistent across Claude Code surfaces.Install all hooks at once:
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- all
Windows (PowerShell 7+) — native PS1 hooks, no bash or jq required. Requires PowerShell 7 (pwsh), not the built-in Windows PowerShell 5. Start with the same recommended safety set:
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } recommended"
Or install all standalone hooks at once:
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } all"
Manage hooks:
# See what's installed
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- list
# Test all installed hooks with real payloads (run after CC updates)
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- verify
# Upgrade all installed hooks to latest
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- upgrade
# Remove a hook (files + settings.json)
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- uninstall read-once
# Remove all hooks
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- uninstall all
# Snapshot settings.json before updating Claude Code
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- backup
# Restore after an auto-update wipes your hooks
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- restore
# Run safety audit on your Claude Code setup
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- check
# Run strict safety audit with hook payload verification
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- check --verify --strict
# Diagnose installation health (files, settings, permissions)
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- doctor
# Show all commands and available hooks
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- help
Windows equivalents (PowerShell syntax):
# List, verify, upgrade, check, uninstall, doctor, backup/restore, help
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } list"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } verify"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } upgrade"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } check"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } check --verify --strict"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } doctor"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } uninstall read-once"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } backup"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } restore"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } help"
install.ps1 verify and install.ps1 doctor use native PowerShell hooks. The
install.ps1 check command runs the bash-based safety-check audit, so it needs
Git Bash, WSL, or another bash on PATH.
Or pick individual hooks:
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/read-once/install.sh | bash
Saves ~2000 tokens per prevented re-read. Includes diff mode for edit-verify-edit workflows (80-95% token savings on changed files).
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/file-guard/install.sh | bash
Define protected files in .file-guard (one pattern per line). Two modes: write-protect (default) blocks writes, edits, and destructive bash commands. [deny] blocks all access including Read, Grep, and Glob, useful for large codegen directories where Claude should use an MCP server instead of reading files directly. Resolves symlinks to prevent bypass via symbolic links. Handles absolute paths (v2.1.89+ compatibility). ~140 tests (bash + PowerShell).
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/git-safe/install.sh | bash
Blocks git push --force, git reset --hard, git checkout ., git checkout HEAD -- path, git restore, git clean -f, git branch -D, --no-verify, and other destructive git commands. Prevents the exact pattern that destroyed 30+ files despite 100+ CLAUDE.md rules. Suggests safer alternatives. Allowlist via .git-safe config. ~1