Boucle-framework

# 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`
- Generate a self-reported README badge after reproducible 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 --badge`
- Dry-run a hook without starting Claude Code:
  `git clone https://github.com/Bande-a-Bonnot/Boucle-framework.git && cd Boucle-framework && bash tools/test-hook.sh "bash tools/bash-guard/hook.sh" --command "rm -rf /" --expect-deny`
- Run the ready-made bash-guard dry-run batch:
  `bash tools/test-hook.sh "bash tools/bash-guard/hook.sh" --batch tools/test-hook-bash-guard-examples.jsonl`
- Run the built-in verifier against Boucle's hooks:
  `python3 tools/test-hook-verify.py`

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 installed
  `PreToolUse` hook scripts. Other hook events are inventoried and reported,
  but skipped for payload verification because they do not receive `PreToolUse`
  tool payloads. 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.
- `test-hook.sh` feeds synthetic `PreToolUse` JSON payloads to local hook
  scripts and reports allow, deny, crash, or timeout behavior. It is useful for
  testing Boucle or third-party hooks before a live Claude Code session, but it
  does not prove Claude Code loaded those hooks from settings.
- 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.
- Public support and team handoff reports should also say whether a fresh
  Claude Code session was started from the verified root after install, upgrade,
  restore, or repair.
- After Claude Code, hooks, settings, MCP servers, connectors, or plugins
  change, capture `--verify --summary-only` from the same project root first,
  then run strict verification and start a fresh Claude Code session from that
  verified root before trusting destructive commands, repository writes, network
  actions, credential reads, or publication.
- For resumed or compacted Claude Code sessions, do not assume disk changes
  reloaded into the active process. Verify from disk, start a fresh session, and
  run one harmless canary through the boundary you care about.
- For MCP/plugin changes, treat new tools, missing tools, changed schemas,
  changed descriptions, unexpected server URLs, failed read-only probes, or a
  connector crossing into send/delete/publish behavior as a renewed approval
  event even when local hook verification is clean.
- If the next intended action is commit, push, or public report, inspect the
  staged diff, destination branch, and remote target separately. A safety
  summary proves only the hook boundary, not that pending content is safe to
  publish.
- The README badge is self-reported from `safety-check --verify --badge`. It
  is a local status label, not a certification. Remove it when you cannot
  reproduce the same tier from the documented project root.
- 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
- Secret pre-push review: https://framework.boucle.sh/recipes.html#secret-pre-push
- Nested Claude billing check: https://framework.boucle.sh/recipes.html#nested-claude-billing
- Write coverage canary: https://framework.boucle.sh/recipes.html#write-coverage-canary
- 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
- Self-reported README badge:
  https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/safety-check/BADGE.md
- 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
- Resumed session recheck: https://framework.boucle.sh/recipes.html#resumed-session
- MCP/plugin update recheck: https://framework.boucle.sh/recipes.html#mcp-plugin-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
- README badge guide: https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/safety-check/BADGE.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
- Local hook dry-run helper: https://github.com/Bande-a-Bonnot/Boucle-framework/blob/main/tools/test-hook.sh

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`