Boucle-framework

Name: Boucle-framework
Author: Bande-a-Bonnot

Verified

Autonomous agent framework with structured memory, safety hooks, and loop management. Built by the agent that runs on it.

115stars

9forks

Shell

Installation

# Add to your Claude Code skills
git clone https://github.com/Bande-a-Bonnot/Boucle-framework

Getting Started

Guides for using ai agents skills like Boucle-framework.

Caveman: Cut Claude Token Use by 65%
How agent-side prompt compression works, when to use it, and when not to.
What is an AI Skills Marketplace?
Definitions, how marketplaces work, and how to choose between them in 2026.
Getting Started with AI Skills

Security ReportVerified

Last scanned: 5/30/2026

{
  "issues": [],
  "status": "PASSED",
  "scannedAt": "2026-05-30T17:05:07.436Z",
  "npmAuditRan": true,
  "pipAuditRan": true
}

README.md

Frequently Asked Questions

What is Boucle-framework?

Boucle-framework is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by Bande-a-Bonnot. Autonomous agent framework with structured memory, safety hooks, and loop management. Built by the agent that runs on it. It has 115 GitHub stars.

Is Boucle-framework safe to use?

Yes. Boucle-framework passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.

How do I install Boucle-framework?

Clone the repository with "git clone https://github.com/Bande-a-Bonnot/Boucle-framework" and add it to your Claude Code skills directory (see the Installation section above).

What programming language is Boucle-framework written in?

Boucle-framework is primarily written in Shell. It is open-source under Bande-a-Bonnot on GitHub, so you can review or fork the full source.

Are there alternatives to Boucle-framework?

Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh Boucle-framework against similar tools.

Agentic AI for Beginners

Build your first AI agent from scratch - tool use, ReAct pattern, memory, deployment

41 minBeginner

Comments (0)

to leave a comment.

No comments yet. Be the first to share your thoughts!

Related Skills

superpowers

by obra

An agentic skills framework & software development methodology that works.

234,966

sidekick-dev-web MakoCode

Boucle

Claude Code hooks that actually enforce your rules. 7 installable hooks, plus enforcement and audit tooling, 1,900+ tests, 932 known Claude Code gaps documented with severity ratings and workarounds.

Quick links: Check your setup · Install hooks · Read-only audits · Individual hooks · Platform support · Recommended Claude Code version · Troubleshooting · Boucle Framework (optional, for autonomous agents)

Claude Code Hooks

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.

What 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

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. Also warns when deny rules are configured without bash-guard, since deny patterns can be bypassed by compound commands and multi-line scripts. No installation required. 415 tests.

For a 10-minute path from audit to verified hooks, see the safety-check quickstart.

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:

Run install.sh verify first (install.ps1 verify on Windows). A clean install is not proof the hooks are firing.
Run 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.
On Windows, use PowerShell 7 (pwsh), not Windows PowerShell 5.
If you write custom deny hooks, prefer 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:

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

# 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 (same commands, 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) } 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"

Or pick individual hooks:

read-once — Stop redundant file reads

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).

file-guard — Protect files from AI access or modification

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).

git-safe — Prevent destructive git operations

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. ~145 tests (88 bash + 57 PowerShell).