Boucle Framework

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. A clean install is not proof the hooks are firing.
• Run install.sh doctor next. 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, upgrade, check, uninstall, doctor, backup/restore
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) } 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"

Or pick individual hooks:

[read-once](tools/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](tools/read-once/#diff-mode-opt-in) for edit-verify-edit workflows (80-95% token savings on changed files).

[file-guard](tools/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](tools/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. ~134 tests (77 bash + 57 PowerShell).

[bash-guard](tools/bash-guard/) — Block dangerous bash commands

curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/bash-guard/install.sh | bash

Blocks dangerous commands across these categories:

• File destruction -- rm -rf /, shred, truncate -s 0, mass delete (find -delete, xargs rm, git clean -f)
• Privilege escalation -- sudo, pkexec, doas, pipe-to-shell (curl|bash)
• Disk utilities -- diskutil eraseDisk/eraseVolume/partitionDisk, fdisk, gdisk, parted, wipefs (#37984: 87GB personal data destroyed)
• Database destruction -- DROP TABLE, prisma db push, dropdb, migrate:fresh, FLUSHALL, and [10+ ORM variants](tools/bash-guard/)
• Credential exposure -- env/printenv, bash -x, cat .env, SSH keys, [programmatic dumps](tools/bash-guard/) (os.environ, process.env)
• Data exfiltration -- curl -d @file, wget --post-file, `nc host The hooks above work standalone. Everything below is optional, for teams running autonomous AI agents in production.

Boucle Framework

An opinionated framework for running autonomous AI agents in a loop. Wake up. Think. Act. Learn. Repeat.

Built by the agent that runs on it. Boucle is developed and maintained by an autonomous agent that uses the framework for its own operation.

Features

• Structured loop runner — Schedule agent iterations via cron/launchd with locking and logging
• Persistent memory (Broca) — File-based, git-native knowledge with BM25 search, temporal decay, garbage collection, cross-reference boost, and duplicate consolidation. No database required.
• Self-observation engine — Track friction, failure, waste, and surprise signals across loops. Fingerprint recurring patterns, deploy responses, measure whether they work. The agent observing its own behavior over time.
• MCP server — Expose Broca memory as a Model Context Protocol server for multi-agent collaboration
• Approval gates — Human-in-the-loop for anything with external consequences
• DX commands — doctor checks your setup, validate catches config mistakes, stats shows loop history
• Audit trail — Every action logged, every decision traceable, every iteration committed to git
• Zero infrastructure — No cloud services, no databases, no Docker required. Just files, git, and a shell

Quick Start

Option 1: Download a binary

Grab the latest release from GitHub Releases.

# macOS (Apple Silicon)
tar xzf boucle-*-aarch64-apple-darwin.tar.gz
mv boucle /usr/local/bin/

Option 2: Build from source

git clone https://github.com/Bande-a-Bonnot/Boucle-framework.git
cd Boucle-framework
cargo build --release

Run your first agent

# Initialize a new agent
boucle init --name my-agent

# Check your setup
boucle doctor

# Preview what happens (no LLM needed)
boucle run --dry-run

# Run one iteration (requires claude CLI)
boucle run

# Set up hourly execution
boucle schedule --interval 1h

Memory System (Broca)

Broca is a file-based, git-native knowledge system for AI agents. Memories are Markdown files with YAML frontmatter.

# Store a memory
boucle memory remember "Python packaging" "Modern projects use pyproject.toml" --tags "python,packaging"

# Search memories
boucle memory recall "python packaging" --limit 5

# Search by tag
boucle memory search-tag "security"

# Add a journal entry
boucle memory journal "Discovered API rate limits are 100/min"

# View statistics
boucle memory stats

Memory entries look like this:

---
type: fact
tags: [python, packaging]
confidence: 0.9
learned: 2026-02-28
source: research
---

# Python packaging has moved to pyproject.toml

setuptools with setup.py is legacy. Modern Python projects use pyproject.toml
with build backends like hatchling, flit, or setuptools itself.

Broca also supports:

• BM25 search — Relevance ranking normalized by document length and term rarity
• Temporal decay — Recent memories score higher; access frequency tracked automatically
• Garbage collection — Archive superseded, low-confidence, or stale entries (reversible, dry-run by default)
• Cross-reference boost — Related entries surface together in search results
• Consolidation — Detect and merge near-duplicate memories using Jaccard similarity
• Confidence tracking — boucle memory update-confidence
• Superseding — boucle memory supersede when knowledge evolves
• Relationships — boucle memory relate to link entries
• Reindexing — boucle memory index to rebuild the search index

Self-Observation Engine

Agents with memory recall what happened. Agents with self-observation notice what keeps happening and develop responses to it.

# Log a signal when something goes wrong
boucle signal friction "auth keeps failing on retry" auth-flaky

# Run the pipeline (harvest → classify → score → promote)
boucle improve run

# See what patterns have emerged
boucle improve status

The engine tracks four signal types: friction (something was harder than it should be), failure (something broke), waste (effort that produced nothing), surprise (unexpected behavior).

Signals with the same fingerprint accumulate into patterns. When a pattern recurs enough, the engine surfaces it as a pending action. You deploy a response (a script, a config change, a new hook), and the engine tracks whether that response actually reduces the signal rate.

Pluggable harvesters: Scripts in improve/harvesters/ run automatically and detect signals from logs, metrics, or any source. Each receives the agent root as $1 and outputs JSONL signals to stdout.

# Initialize with an example harvester
boucle improve init

MCP Server

Boucle exposes Broca as a Model Context Protocol server, so other AI agents can share memory.

# Start MCP server (stdio transport)
boucle mcp --stdio

# Or HTTP transport
boucle mcp --port 8080

Available tools: broca_remember, broca_recall, broca_journal, broca_relate, broca_supersede, broca_stats, broca_gc, broca_consolidate

Works with Claude Desktop, Claude Code, or any MCP-compatible client.

All Tools

Each tool has its own README with full documentation: [read-once](tools/read-once/), [file-guard](tools/file-guard/), [git-safe](tools/git-safe/), [bash-guard](tools/bash-guard/), [branch-guard](tools/branch-guard/), [session-log](tools/session-log/), [enforce-hooks](tools/enforce/), [safety-check](tools/safety-check/), [worktree-guard](tools/worktree-guard/), [diagnose](tools/diagnose/), [test-hook](tools/test-hook.sh).

Architecture

your-agent/
├── boucle.toml          # Agent configuration
├── system-prompt.md     # Agent identity and rules (optional)
├── allowed-tools.txt    # Tool restrictions (optional)
├── memory/              # Persistent knowledge (Broca)
│   ├── state.md         # Current state — read at loop start, updated at loop end
│   ├── knowledge/       # Learned facts, indexed by topic
│   └── journal/         # Timestamped iteration summaries
├── goals/               # Active objectives
├── log

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Bande-a-Bonnot](https://github.com/Bande-a-Bonnot)
- **Source:** [Bande-a-Bonnot/Boucle-framework](https://github.com/Bande-a-Bonnot/Boucle-framework)
- **License:** MIT
- **Homepage:** https://framework.boucle.sh/

Install and usage instructions live in the source repository linked above.