Boucle Framework
Autonomous agent framework with structured memory, safety hooks, and loop management. Built by the agent that runs on it.
Last verified:
What is Boucle Framework?
Boucle Framework is an opinionated framework for running autonomous AI agents in a continuous loop, built by the agent that runs on it. The framework provides a structured loop runner that schedules agent iterations via cron or launchd with locking and logging, enabling agents to wake up, think, act, and learn in repeated cycles. Each iteration follows a five-step process: Wake (read memory and goals), Think (analyze state and decide actions), Act (write code, research, create proposals), Learn (update memory), and Sleep (commit to git and wait for next iteration).
The framework's core feature is the Broca memory system, a file-based, git-native knowledge system that requires no database. Broca provides BM25 search with relevance ranking, temporal decay (recent memories score higher), garbage collection for stale entries, cross-reference boost, duplicate consolidation using Jaccard similarity, and confidence tracking. Memories are stored as Markdown files with YAML frontmatter, making them human-readable and git-diffable. The framework also includes an MCP server that exposes Broca memory as Model Context Protocol tools for multi-agent collaboration.
Boucle includes strict approval gates for anything with external consequences (spending money, posting publicly, contacting people), ensuring human-in-the-loop control. The self-observation engine tracks friction, failure, waste, and surprise signals across loops, fingerprinting recurring patterns and measuring whether deployed responses reduce signal rates. Additional features include session-log for auditing every tool call to JSONL, enforce-hooks to turn CLAUDE.md rules into deterministic enforcement, and comprehensive CLI tools like doctor, validate, stats, and schedule.
The framework is designed for developers and teams building autonomous AI agents that need persistent memory, audit trails, and safety boundaries. It targets users of Claude Code who want agents that run continuously rather than one-shot interactions. The hooks component (bash-guard, git-safe, file-guard, branch-guard, read-once, worktree-guard, enforce-hooks, safety-check, session-log) also works standalone to prevent Claude Code from running dangerous commands, deleting files, or ignoring rules.
Boucle Framework pricing
Pricing model: Freemium
Free and open-source under the MIT license. Available on GitHub at github.com/Bande-a-Bonnot/Boucle-framework. Pre-built binaries for macOS (Apple Silicon), Linux, and Windows are available on the GitHub Releases page at no cost. No paid tiers, subscriptions, or enterprise plans. All features including the loop runner, Broca memory system, MCP server, approval gates, safety hooks, and CLI tools are completely free with zero infrastructure costs.
Boucle Framework pros
- Persistent file-based memory with no database required
- Git-native audit trail with every iteration committed
- BM25 search with relevance ranking and temporal decay
- Built-in approval gates for dangerous actions
- Self-observation engine tracks friction, failure, waste, surprise signals
- MCP server exposes memory for multi-agent collaboration
- Zero infrastructure: no cloud services or Docker needed
- 7 installable safety hooks for Claude Code
- bash-guard blocks 590+ dangerous command patterns including cloud infrastructure deletion
- git-safe prevents force push, reset --hard, checkout . and other destructive operations
- file-guard protects .env, certificates, SSH keys with symlink resolution
- read-once saves 30%+ tokens by stopping redundant file reads
- enforce-hooks turns CLAUDE.md rules into deterministic code-level enforcement
- Native PowerShell support for Windows users (no bash or jq needed)
- ~1758 tests across all hooks with 932 documented Claude Code gaps
- CLI tools include doctor, validate, stats, schedule for easy management
- Pre-built binaries available on GitHub releases for quick installation
- Context plugins and lifecycle hooks for extensibility
- Garbage collection consolidates near-duplicate memories automatically
Boucle Framework cons
- Windows native PowerShell hooks have only ~18% reliability compared to full on macOS/Linux
- Best experience requires macOS or Linux, Windows users should use WSL
- Hooks only fire on tool calls, not on prompt assembly or @-autocomplete
- Internal git operations (fetch + reset every ~10 minutes) bypass all hooks and can destroy uncommitted changes
- Permission state can desync mid-session when settings.local.json is edited during a session
- IS_DEMO=1 or CLAUDE_CODE_SIMPLE environment variables silently disable all hooks
- --bare CLI flag disables hooks, LSP, plugin sync for scripted calls
- SessionEnd hooks killed before completion for async work like API calls
- Non-interactive sessions hang permanently on usage limit prompts with no programmatic workaround
- Symlinked .claude/ directories not discovered on Linux causing hook failures
- Background agents spawned via Agent tool cannot be reliably terminated by user
Frequently asked questions about Boucle Framework
What is Boucle Framework?
Boucle is an opinionated framework for running autonomous AI agents in a continuous loop. It provides a structured loop runner, persistent file-based memory called Broca (git-native, no database), an MCP server for multi-agent collaboration, approval gates for dangerous actions, a self-observation engine tracking friction/failure/waste/surprise signals, and comprehensive CLI tools. The framework is built by the agent that runs on it, creating a feedback loop where improvements directly benefit the agent's capabilities.
What does bash-guard block?
bash-guard blocks dangerous commands across categories: file destruction (rm -rf /, shred, truncate, mass delete), privilege escalation (sudo, pkexec, doas, curl|bash), disk utilities (diskutil eraseDisk, fdisk, parted, wipefs), database destruction (DROP TABLE, prisma db push, dropdb, migrate:fresh), credential exposure (env, cat .env, SSH keys), data exfiltration (curl -d @file, nc host < file), cloud infrastructure (terraform destroy, kubectl delete, aws ec2 terminate, az group delete), Docker destruction, system databases, and git force push. It evaluates compound commands, catches multi-line comment bypasses, and detects encoding obfuscation attempts.
How does Broca memory work?
Broca is a file-based, git-native knowledge system where memories are Markdown files with YAML frontmatter containing type, tags, confidence, learned date, and source. It provides BM25 search with relevance ranking normalized by document length and term rarity, temporal decay (recent memories score higher with automatic access frequency tracking), garbage collection for stale/superseded entries, cross-reference boost for related entries, duplicate consolidation using Jaccard similarity, confidence tracking via boucle memory update-confidence, superseding for evolving knowledge, and relationship linking between entries.
What are approval gates?
Approval gates require human-in-the-loop approval for anything with external consequences like spending money, posting publicly, contacting people, or pushing to public repos. The human (Thomas for the Boucle agent) reviews and approves these actions before execution. He is legally, reputationally, and financially responsible for everything the agent does. Pending approvals are stored in the gates/ directory and the agent cannot proceed without human review.
How do I run an autonomous agent with Boucle?
First, download a pre-built binary from GitHub Releases or build from source with cargo build --release. Initialize a new agent: boucle init --name my-agent. Check setup: boucle doctor. Preview without calling LLM: boucle run --dry-run. Run one iteration (requires claude CLI): boucle run. Set up scheduled execution: boucle schedule --interval 1h for hourly runs. The agent will then wake every 15 minutes (or your configured interval), read memory, decide what to do, execute, learn, and commit to git.
What is the self-observation engine?
The self-observation engine lets agents notice what keeps happening and develop responses. It tracks four signal types: friction (something harder than it should be), failure (something broke), waste (effort producing nothing), and 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 (script, config change, new hook) and the engine tracks whether it reduces the signal rate. Use boucle signal <type> <summary> <fingerprint> to log signals and boucle improve run to run the pipeline.
Do the hooks work on Windows?
Yes, 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. However, native PowerShell hooks have only ~18% reliability because Claude Code fires them inconsistently (issue #37988). For full reliability on Windows, use WSL with bash hooks instead. enforce-hooks and safety-check require WSL or Git Bash on Windows.
What Claude Code version should I use?
Use v2.1.90 or later. Earlier versions have hook-related regressions: v2.1.89 was pulled from npm (custom commands broken, systemMessage display broken, source map leak), v2.1.81-84 have permission bypass resets mid-session when PreToolUse hooks are installed, and versions before v2.1.50 lack hookSpecificOutput format support. Run claude --version to check and safety-check with --verify to confirm hooks fire correctly on your version.
Why are my hooks not blocking commands?
Common causes: JSONC comments in settings.json silently stop hooks (claude-code#37540) - installers auto-strip comments but check manually; IS_DEMO=1 environment variable disables all hooks; CLAUDE_CODE_SIMPLE environment variable disables hooks, MCP tools, attachments, and CLAUDE.md loading; --bare CLI flag disables hooks for scripted calls; hooks only fire on tool calls not prompt assembly; permission state desyncs when settings.local.json is edited mid-session. Run install.sh doctor to diagnose, check environment variables with echo $IS_DEMO and echo $CLAUDE_CODE_SIMPLE, and use safety-check --verify for live verification.