Banh Mi Guard (guard)
guard wraps coding workflows in an automated safety harness that verifies changes before and after execution. It runs two gates around each task: a pre-task scope check and a post-task verification gate combining deterministic diff checks, static rules, project invariants, and an LLM review.
Live Documentation: https://okrath.github.io/banh-mi-guard/
Cross-Platform Installation (Windows, Linux, macOS)
Install the guard CLI globally on any platform:
# Recommended: Isolated global installation with pipx
pipx install banh-mi-guard
# Or with standard pip across all platforms:
pip install banh-mi-guard
For environment $PATH configuration, installation from GitHub main, and optional Alibaba OCR CLI setup, see CLI Reference: Installation & Environment Setup.
Five-Minute Quickstart
Integrate guard into your workflow in four simple steps:
# 1. PRE-TASK: Declare scope and capture baseline before editing code
guard pre "Implement mobile responsive navigation drawer" --scope src/components/nav
# 2. EDIT: Modify code using your AI agent (Claude Code, Cursor, Codex, etc.) or editor
# 3. POST-TASK: Verify diffs, static security rules, build health, and LLM approval
guard post
# 4. COMMIT: Commit approved changes (approvals are HMAC-signed; unapproved commits or unsigned older sessions are blocked)
git commit -m "feat: add responsive navigation drawer"
To run deep repository inspection with Alibaba OCR, use guard post --full. For a large or security-sensitive change, the post report asks you (through your agent) whether you want a deeper review by a panel of three reviewers, a full OCR review, or both.
Three-Pillar Architecture
Every modification is verified before and after execution across three layers:
- Deterministic Pre-Task Gate (0 tokens): Locks declared scope boundaries, records baseline snapshots, and evaluates project invariants.
- Deterministic Post-Task Verification (0 tokens): Audits diff blast radius, runs compilation/tests, checks for deleted references (
DEAD-REF), evaluates static rules (SEC-001 to SEC-008), and detects code hygiene issues.
- Generative LLM Review: Configured LLM (Claude, GPT, DeepSeek, Ollama, or local agent CLIs) evaluates batched diffs and verified evidence for a final
APPROVED or REVISE verdict. Most of its findings are advisory review comments; the hard blocking comes from the deterministic checks of pillars 1 and 2 (see Scoring and the final verdict). Approved sessions receive a cryptographic HMAC signature required by Git commit hooks.
For architectural diagrams, taxonomy, and security specifications, see Architecture Specification.
Command Overview
- Verification Harness (
guard pre, guard post, guard run): Enforces the Sandwich Pattern. guard pre sets scope and invariant baselines; guard post audits diffs, executes test suites, and requests gate approval; guard run wraps external commands in both gates atomically. See CLI Reference: Pre & Post.
- Project Invariants (
guard invariants): Enforces domain and team behavioral invariants without token costs using regex checks across local (.guard/invariants.json) and shared (guard.invariants.json) files. See CLI Reference: Invariants.
- Agent & Hook Integration (
guard install, guard hook, guard agent, guard uninstall): Configures Git hooks (core.hooksPath) and injects directives into global agent instruction files (CLAUDE.md, AGENT.md). Agent hook adapters intercept edit tools to block out-of-scope or unauthorized modifications. See CLI Reference: Installation & Hooks.
- Configuration & Setup (
guard config, guard setup): Interactive wizards for configuring LLM credentials (APIs or local agent CLIs like claude, codex, omp), syncing settings to Alibaba OCR, and choosing commit message policies. See CLI Reference: Configuration.
- Review, Findings & Approvals (
guard review, guard finding, guard accept, guard reset): Runs on-demand LLM diff reviews, tracks deferred or rejected findings, provides an interactive decision screen when review budgets are exhausted, and archives sessions. See CLI Reference: Review & Accept.
Documentation & Quality Reference
- 📖 CLI Command Reference: Complete option flags, syntax, and operational rules for every command.
- 🏛️ Architecture Specification: Detailed system taxonomy, defense layers, state isolation, and HMAC approval signing.
- 🔎 Review Options, Stages & Limits: Optional review stages of
guard post (reviewer panel, finding validation, test evidence, threat frame), what they cost, and the Not reviewed / limits section of the report. Developer-only measurement tool: Benchmark.
- 🛡️ Quality Pillars & Matrix: 2D quality matrix (domains × pillars), static rule catalog, and scoring rules.
- 🚀 Releasing Guide: Release process, version tagging, and PyPI trusted publishing workflow.
- 🌐 Live Documentation Website: Interactive documentation guide and full feature matrix.
Running the Test Suite
Run the integration and unit test suite locally:
pytest
