boucle

The problem

Claude Code's CLAUDE.md rules are probabilistic, not deterministic. Its permission system has known bypass patterns. Users have lost 87GB of personal data, had 30+ files destroyed despite 100+ rules, and seen explicit instructions ignored.

These hooks enforce boundaries that text rules and permissions can't. Zero dependencies beyond bash and jq. ~1758 tests. 932 known Claude Code gaps documented with severity ratings and workarounds.

Check your setup

Scores your Claude Code safety configuration from A to F. Shows one-liner fixes for each gap. No installation required.

Start with the essentials

Installs bash-guard + git-safe + file-guard: the safety net every Claude Code user should have. Block dangerous commands, prevent destructive git operations, protect sensitive files.

Install all hooks

Or pick individual hooks:

• enforce-hooks — turn CLAUDE.md rules into actual enforcement. Your rules say "never edit .env" but Claude edits it anyway. This reads your rules and blocks violations deterministically. One dynamic hook, re-reads CLAUDE.md on every tool call. Self-protection mode (--armor) prevents Claude from deleting its own hooks. ~71 tests. Details.
  
  $ curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/enforce/install.sh | bash
• safety-check — audit your Claude Code setup in 5 seconds. Scores your configuration from A to F, shows one-liner fixes for each gap, detects 20+ platform bugs and permission pitfalls that silently break your setup (colon in paths, deny+denyWrite conflicts, bypassPermissions resets, and more), scans your CLAUDE.md for rules that could be enforced by hooks. No installation required. ~267 tests.
  
  $ curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash
• read-once — stops Claude Code from re-reading files already in context. Diff mode shows only what changed. Saves 30%+ tokens per session.
  
  $ curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/read-once/install.sh | bash
• file-guard — protects .env, certificates, SSH keys, and other sensitive files. Write-protect (default) blocks edits; deny mode blocks all access including reads. Resolves symlinks to prevent bypass via symbolic links.
  
  $ curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/file-guard/install.sh | bash
• git-safe — prevents destructive git operations (force push, push --delete, reset --hard, checkout ., checkout HEAD -- path, restore, clean -f, branch -D, --no-verify). Suggests safer alternatives.
  
  $ curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/git-safe/install.sh | bash
• bash-guard — blocks dangerous bash commands (rm -rf /, sudo/pkexec/doas, curl|bash, chmod -R 777, disk utilities (diskutil erase, fdisk, parted, wipefs), Docker destruction, database drops, credential exposure, cloud infra deletion (terraform destroy, kubectl delete/drain/scale-to-zero, helm uninstall, aws ec2 terminate/rds delete/cloudformation delete-stack, az group delete, doctl destroy, flyctl destroy, heroku apps:destroy, vercel rm, netlify sites:delete), mass file deletion, shred, truncate, data exfiltration, programmatic env dumps, sensitive file reads, system database corruption, mount point destruction, git push --force). Detects encoding bypasses (base64/hex decode piped to shell, reversed strings, process substitution downloads). Catches programming language shell wrappers (python subprocess, ruby system, perl exec, node child_process). Evaluates compound commands. Catches multi-line comment bypass (#38119). 590 verified bash tests, with additional PowerShell coverage when pwsh is available.
  
  $ curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/bash-guard/install.sh | bash
• branch-guard — prevents direct commits to protected branches (main, master, production, release). Forces feature-branch workflow.
  
  $ curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/branch-guard/install.sh | bash
• worktree-guard — prevents data loss when exiting worktrees. Blocks exit if there are uncommitted changes, untracked files, unmerged commits, or unpushed commits. Addresses #38287.
  
  $ curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/worktree-guard/install.sh | bash
• session-log — audit trail that logs every tool call to JSONL. See what Claude did: files read/written, commands run, timestamps.
  
  $ curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/session-log/install.sh | bash

Common problems

Detailed recipes with issue references and install commands →

• Claude deleted my files — install bash-guard + git-safe. They block rm -rf, git checkout ., git reset --hard, and 25+ other destructive patterns.
• Claude ignores my CLAUDE.md rules — install enforce-hooks. Turns text rules into deterministic code-level enforcement.
• Claude runs commands I told it not to — install bash-guard. Evaluates every command segment, catches compound commands and multi-line bypass.
• I want to see what Claude is doing — install session-log. Logs every tool call with timestamps to JSONL.
• Claude edits sensitive files — install file-guard. Protects .env, certificates, SSH keys. Write-protect or full deny.
• Claude commits to main — install branch-guard. Forces feature-branch workflow on protected branches.
• Worktree exit loses my commits — install worktree-guard. Blocks exit until changes are committed, merged, or pushed.
• I'm on Windows — all seven hooks ship with native PowerShell equivalents (hook.ps1): bash-guard, file-guard, git-safe, branch-guard, read-once, worktree-guard, and session-log. No jq or bash needed. Use pwsh -File hook.ps1 in your settings.

Agent framework

The hooks above work standalone. The framework below is for running autonomous AI agents in a loop.

Or download a pre-built binary from the releases page.

• Loop runner — schedule via cron/launchd, with locking and logging
• Broca memory — BM25 search, temporal decay, garbage collection. Git-native, no database
• MCP server — expose memory as Model Context Protocol tools
• Approval gates — human-in-the-loop for anything with consequences

198 Rust tests. Pre-built binaries on the releases page.

Links

• Recipes common problems & solutions
• Known Limitations 932 documented, searchable
• GitHub source
• Blog blog.boucle.sh
• Home boucle.sh