Boucle-framework

Intercepts Claude Code tool invocations at the PreToolUse and PostToolUse lifecycle hooks, executing hard-coded Bash/PowerShell scripts that return definitive deny decisions based on file paths, command patterns, and git state. Unlike probabilistic CLAUDE.md rules that degrade with context growth, these hooks enforce boundaries through portable shell scripts requiring only jq, ensuring consistent enforcement across any environment where Claude Code runs.

A Rust-based loop runner (src/main.rs) that manages the complete lifecycle of autonomous Claude Code execution: reading configuration from boucle.toml, assembling context from memory and plugins, invoking Claude Code in a loop, capturing tool execution results, and persisting state back to the Broca memory system. The runner implements fail-safe semantics, allowing graceful degradation when hooks block operations, and integrates with the Self-Observation Engine (Improve) to enable agents to reflect on their own performance.

A Python-based tool that automates the installation, configuration, and enforcement of all Boucle safety hooks across an environment. The enforce-hooks script reads hook specifications, validates prerequisites (Bash/PowerShell version, jq availability), installs hooks to the correct locations, and configures them with project-specific allowlists/blocklists. It also provides an 'enforce' mode that validates all hooks are active before allowing agent execution.

A structured database of known agent limitations, bypass patterns, and mitigations that is accessible through a web interface. The system allows teams to document discovered hook bypasses, edge cases, and limitations in a centralized location, enabling knowledge sharing across agent deployments. The web interface provides search and filtering capabilities to help developers understand what protections are in place and what gaps remain.

An MCP (Model Context Protocol) server that exposes Boucle's Broca memory system and agent capabilities as tools available to Claude Desktop. The server implements standard MCP tool definitions, allowing Claude to query agent memory, trigger agent loops, and inspect execution state directly from the Claude Desktop interface. This enables interactive debugging and manual agent control without requiring command-line access.

A TOML-based configuration file that defines agent behavior, memory paths, plugin locations, hook policies, and execution schedules. The Boucle loop runner reads boucle.toml at startup, assembling the complete agent context from the configuration. This enables teams to version-control agent configuration alongside code and enables rapid agent setup without code changes.

A memory architecture that stores agent state as standard Markdown and YAML files in the git repository, making agent knowledge and execution history human-readable, version-controlled, and auditable. The Broca system uses a structured schema for memory entries, enabling the Self-Observation Engine to query and update memory programmatically while maintaining git history for debugging and rollback. This approach eliminates the black-box nature of vector databases and enables agents to reason about their own memory.

A subsystem that enables agents to query their own Broca memory, analyze past execution outcomes, and generate improvement strategies without human intervention. The Improve engine reads execution logs and memory state, identifies patterns in successes and failures, and updates agent knowledge or strategy documents in the memory system. This creates a feedback loop where agents can reason about their own performance and adapt behavior across execution cycles.

A Bash/PowerShell hook that intercepts file operations (read, write, delete) by pattern-matching against a configurable allowlist/blocklist of file paths. The hook executes as a PreToolUse interceptor, examining the file path argument of operations like 'edit_file' or 'delete_file' and returning a deny decision if the path matches blocked patterns (e.g., /etc/*, .env, secrets/*). This provides granular, filesystem-level protection without requiring kernel-level access controls.

A Bash/PowerShell hook that intercepts shell command execution by analyzing the command string before invocation. The hook pattern-matches against a blocklist of dangerous command patterns (e.g., 'rm -rf /', 'sudo', 'curl | bash') and returns a deny decision if the command matches a blocked pattern. This operates at the PreToolUse stage, preventing dangerous commands from ever reaching the shell.

A pair of hooks that enforce git-specific safety policies: git-safe prevents direct commits to protected branches (main, master, production) and enforces commit message validation, while branch-guard ensures agents only create/delete branches matching approved naming patterns. These hooks operate as PreToolUse interceptors on git commands, examining the branch name and commit message before allowing git operations to proceed.

A pair of hooks that provide execution isolation and audit trails: worktree-guard ensures agents operate within isolated git worktrees (preventing cross-contamination between concurrent agents), while session-log records all tool invocations, results, and hook decisions to a structured log file. The session-log hook operates as a PostToolUse interceptor, capturing the complete execution context for debugging and compliance auditing.

A safety hook that enforces one-time-read semantics on sensitive files by tracking which files have been read and blocking subsequent reads. The hook operates as a PreToolUse interceptor on file read operations, maintaining a read-once registry in the session state and returning a deny decision if a file has already been read in the current session. This prevents agents from repeatedly accessing secrets or sensitive data.

A comprehensive safety auditing system consisting of two components: safety-check is a Bash script that scans the environment for installed hooks, validates their configuration, and reports on the security posture before agents run; diagnose is a Claude Code plugin that integrates with the auditor to provide real-time diagnostics during agent execution. Together, they enable users to verify safety enforcement is active and identify misconfigured or missing hooks before autonomous execution.