Boucle Claude Code hooks plugin
Boucle-framework
Seven Claude Code hooks block dangerous commands, force pushes and edits to protected files; enforce-hooks enforces CLAUDE.md.
- 126 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The installer is downloaded from the network and edits `settings.json`, and the hooks run on every tool call.
Install
- Works in
Manual install
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- recommendedRun from the project root: installs `bash-guard`, `git-safe` and `file-guard` into `.claude/settings.json`. The script is downloaded from GitHub, so read it first.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The installer is downloaded from the network and edits `settings.json`, and the hooks run on every tool call.
This is third-party code. Review the repository files before installing.
What it does
Boucle installs hooks into Claude Code that fire on tool calls and hard-block violations. `bash-guard` stops destructive shell commands, `git-safe` stops `git push --force` and `git reset --hard`, and `file-guard` shields files listed in `.file-guard`. There are also `branch-guard`, `worktree-guard`, `read-once` against repeated reads and `session-log` with a session journal. `enforce-hooks` reads CLAUDE.md and turns rules marked `@enforced` into checks that run on every call. The `check.sh` script grades a project's protection from A to F, and the `--verify` flag sends test payloads to the hooks to confirm blocking works. The repository also contains the Boucle framework for autonomous agents in a loop; hooks do not need it.
Who it is for. People running Claude Code with broad permissions or unattended who want hard boundaries: protected-file lists, no `git push --force`, no destructive commands.
Good fit when
- An agent works overnight and a guarantee is wanted that it will not run `rm -rf` or `terraform destroy`.
- CLAUDE.md forbids editing `.env` but the model sometimes does, so the rule must become a block.
- Branches `main` and `production` must stay free of direct agent commits.
- After a Claude Code update you want to confirm old hooks still fire.
Not a fit when
- The agent runs outside Claude Code: the hooks are written for its events.
- Protection from a malicious user is needed: hooks catch agent mistakes and do not replace OS permissions.
- The environment forbids running third-party install scripts through `curl | bash`.
Example request
Install the recommended Boucle hook set in this project, run `doctor` and `verify`, and show which commands are now blocked.Limitations
Hooks cover only tool calls that Claude Code routes to them, so `--verify --strict` is run after installation and after every client update. The installer downloads from GitHub and edits `.claude/settings.json`: take a copy first with `backup`. The hooks need `jq` and `python3`, and PowerShell 7 on Windows. JSON with `permissionDecision: deny` behaves inconsistently; blocking through stderr and exit code 2 is more reliable. The repository's last commit is dated 25 September 2026.
How to disable. Run `install.sh uninstall all` or remove one hook with `install.sh uninstall <name>`: files and `settings.json` entries are deleted. Then run `install.sh verify`, which reports that no hooks remain.
FAQ
Which hooks does the recommended set include?
Three: `bash-guard`, `git-safe` and `file-guard`. They cover dangerous commands, destructive git and protected files.
How do I check that hooks really block?
Run `install.sh verify` or `check.sh --verify --strict`. The script sends Claude Code-style test payloads to the hooks and does not run the dangerous commands themselves.
How do I stop the agent from reading a file?
Add a pattern to `.file-guard` under the `[deny]` section. It blocks writes as well as Read, Grep and Glob.
Does it work on Windows?
Yes, through PowerShell 7 and `install.ps1`, without bash or `jq`. The `check` command still needs `bash`, such as Git Bash or WSL.
What does `enforce-hooks` do?
It reads CLAUDE.md, finds rules marked `@enforced` and builds one dynamic hook from them. Run `enforce-hooks.py --scan` to preview the result before installing.
Discussion
No questions or reviews yet.
Related
PluginsA marketplace of 22 hook plugins for Claude Code: safety, cost control, observability and automation
A Claude Code hook that rates Bash command risk with rules and Haiku, asking for approval only on risky commands
Claude Hooks (Prompt Injection Defender)
Claude Hooks
A Claude Code hook that scans file, web page and command output for hidden instructions and warns the agent
A Bash command hook for Claude Code that auto-approves safe commands, stops dangerous ones and steers the agent to another route
Security hook for coding agents: scores each tool call with session context and flags injections in results and skills
A plugin and approval server for Claude Code and Codex: a risky tool call waits for your decision before it runs
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| Boucle Claude Code hooks (this card) | no | 126 | |
| CC Safety Net | no | 2,014 | installs protection across several agents with a policy GUI; Boucle works only in Claude Code but adds an audit, `enforce-hooks` and rollback |
| Destructive Command Guard | no | 6,349 | blocks destructive commands with a single rule; Boucle bundles shell, git, files and branches into a set |
README in short
The README goes from auditing current protection to installing hooks, verifying and rolling back. It separately describes the seven hooks, `enforce-hooks`, a read-only mode and a corpus of known Claude Code gaps.