# Boucle Framework

Boucle Framework is a public, open-source project for Claude Code safety hooks
and autonomous-agent loop infrastructure.

Primary user path:

- Try safety-check without reading real Claude Code settings (Bash 3.2+; the
  default `/bin/bash` on macOS works):
  ```sh
  (
    tmp_home="$(mktemp -d)"
    tmp_project="$(mktemp -d)"
    cleanup() {
      if [ "${KEEP_BOUCLE_FIRST_TEST:-0}" != "1" ]; then
        rmdir "$tmp_home" "$tmp_project" 2>/dev/null || {
          printf 'Temporary directories were not empty; inspect and remove manually:\n'
          printf '  %s\n  %s\n' "$tmp_home" "$tmp_project"
        }
      fi
    }
    trap cleanup EXIT
    cd "$tmp_project"
    curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | PYTHONDONTWRITEBYTECODE=1 HOME="$tmp_home" bash -s -- --verify --summary-only
    if [ "${KEEP_BOUCLE_FIRST_TEST:-0}" = "1" ]; then
      printf 'Temporary HOME: %s\nTemporary project: %s\n' "$tmp_home" "$tmp_project"
    fi
  )
  ```
- Audit a Claude Code setup from the project root:
  `repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"; cd "$repo_root"; curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash`
- Install the recommended hook set:
  `curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- recommended`
- Verify installed hooks:
  `curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- verify`
- Run strict safety-check verification from the project root:
  `repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"; cd "$repo_root"; curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify --strict`
- Ask for public support with a bounded summary from the project root:
  `repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"; cd "$repo_root"; curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify --summary-only`

Native Windows path:

- Use PowerShell 7 (`pwsh`).
- Move to the project root first when inside a git checkout:
  `$root = if (Get-Command git -ErrorAction SilentlyContinue) { git rev-parse --show-toplevel 2>$null }; if ($root) { Set-Location $root }`
- Install the recommended native hook set:
  `iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } recommended"`
- Verify native hooks:
  `iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } verify"`

Important boundaries:

- Safety-check audit mode does not install hooks.
- The hook installers download `tools/install.sh` or `tools/install.ps1` from
  GitHub raw content and run locally. Installing adds managed hook files under
  `~/.claude/<hook-name>/` (`hook.sh` on macOS/Linux, `hook.ps1` on native
  Windows) and updates `~/.claude/settings.json`; it does not upload settings,
  hook files, shell history, repository contents, or safety summary output.
- The isolated first-test path uses a temporary `HOME` and does not prove the
  real setup is safe. It only proves the checker starts and reports an
  unconfigured baseline as unverified.
- Verification sends representative Claude-style JSON payloads to hook scripts.
  It does not execute the dangerous shell or git commands named in those
  payloads.
- Read strict verification as boundary evidence, not as a badge. `Verify: not
  run`, `no hooks found`, `0 payload checks`, `FAIL-OPEN`, or skipped
  `PreToolUse` checks mean the hook layer is still unproven.
- When the summary says `Verify: 0 FAIL-OPEN` with payload checks actually run
  and no skipped boundary hooks, start a fresh Claude Code session from the
  same project root and document residual warnings instead of reinstalling
  repeatedly to chase an A.
- Hooks cover Claude Code tool-call boundaries. They are not a sandbox and do
  not replace backups, OS permissions, containers, or secret-management controls.
- After installing or changing hooks, start a fresh Claude Code session from the
  same project root before relying on the hook boundary.
- For public support, share the bounded safety summary from
  `--verify --summary-only`, not raw settings files, secrets, paths, hook source,
  or private CLAUDE.md rules.
- That support-summary command downloads `tools/safety-check/check.sh` from
  GitHub raw content and runs locally on the current project and Claude Code
  settings. It does not upload settings, hook files, shell history, repository
  contents, session logs, or safety summary output.
- For failures after a Claude Code update, include
  `Pre-update baseline: summary/version captured / not captured / not an update
  issue` so maintainers know whether the new verification result is a
  regression from a known baseline or a first verified result.
  Use `summary/version captured` only when both the old Claude Code version and
  bounded safety summary were recorded before the update.
- Temporary hook trials still edit Claude Code settings while active. Snapshot,
  verify install, uninstall, then verify cleanup.
- A clean native Windows `install.ps1 verify` proves the native PowerShell hooks
  it checks. Use Git Bash or WSL for the full bash-based safety-check summary
  when you need the bounded copy/paste report.
- CI can verify checked-in project hooks and scripts. It cannot prove every
  developer's global `~/.claude/settings.json` is protected.

Core public resources:

- Homepage: https://framework.boucle.sh/
- Recipes: https://framework.boucle.sh/recipes.html
- Known limitations: https://framework.boucle.sh/limitations.html
- Machine-readable limitations JSON: https://framework.boucle.sh/limitations.json
- Limitations Atom feed: https://framework.boucle.sh/limitations-feed.xml
- GitHub repository: https://github.com/Bande-a-Bonnot/Boucle-framework

Use-case entrypoints:

- Isolated first safety-check test: https://framework.boucle.sh/recipes.html#isolated-first-test
- First safety audit: https://framework.boucle.sh/recipes.html#first-audit
- Failed verification triage: https://framework.boucle.sh/recipes.html#verification-failed
- Manual settings or hook edit recheck: https://framework.boucle.sh/recipes.html#manual-settings-edit
- Temporary hook trial and cleanup: https://framework.boucle.sh/recipes.html#temporary-trial
- Native Windows setup: https://framework.boucle.sh/recipes.html#windows-native
- CLAUDE.md rules ignored: https://framework.boucle.sh/recipes.html#rules-ignored
- Read-only audit session: https://framework.boucle.sh/recipes.html#read-only-audit
- Files deleted or overwritten: https://framework.boucle.sh/recipes.html#files-deleted
- Dangerous shell commands: https://framework.boucle.sh/recipes.html#dangerous-commands
- Git resets, force pushes, and destructive cleanup: https://framework.boucle.sh/recipes.html#git-disasters
- Token waste from repeated file reads: https://framework.boucle.sh/recipes.html#token-waste
- Tool switching and fallback bypasses: https://framework.boucle.sh/recipes.html#tool-switching
- Custom hook dry run: https://framework.boucle.sh/recipes.html#custom-hook-test
- Audit trail and claim verification: https://framework.boucle.sh/recipes.html#audit-trail
- Safe public support evidence: https://framework.boucle.sh/recipes.html#support-evidence
- CI verification: https://framework.boucle.sh/recipes.html#ci-verification
- Team handoff report: https://framework.boucle.sh/recipes.html#team-handoff
- Autonomous session preflight: https://framework.boucle.sh/recipes.html#autonomous-session
- Claude Code update recheck: https://framework.boucle.sh/recipes.html#after-update

Repository documentation:

- First test: https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/safety-check/FIRST_TEST.md
- Safety-check quickstart: https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/safety-check/QUICKSTART.md
- Read-only audit mode: https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/enforce/READ_ONLY_AUDIT.md
- CI verification: https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/safety-check/CI.md
- Team handoff: https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/safety-check/TEAM_HANDOFF.md
- Safe support evidence: https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/safety-check/SUPPORT_EVIDENCE.md
- Safe support examples: https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/safety-check/SUPPORT_EXAMPLES.md
- Claude Code update checklist: https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/safety-check/UPDATE_CHECKLIST.md
- Safety summary triage: https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/safety-check/TRIAGE.md

Standalone hooks:

- bash-guard: dangerous shell command blocking
- git-safe: destructive git operation blocking
- file-guard: sensitive file protection
- branch-guard: protected branch commit blocking
- worktree-guard: worktree exit data-loss guard
- read-once: redundant file-read reduction
- session-log: Claude Code tool-call audit trail
- enforce-hooks: CLAUDE.md rule enforcement for covered tool calls

Autonomous-agent framework path:

- Clone: `git clone https://github.com/Bande-a-Bonnot/Boucle-framework.git`
- Build: `cd Boucle-framework && cargo build --release`
- Initialize an agent: `boucle init --name my-agent`
- Dry run: `boucle run --dry-run`
- Run: `boucle run`