Quickstart

This page takes you from nothing to a guarded repo in about three minutes: install the engine, run one command to scaffold rules and the git hook, then watch becwright block a commit that carries a hardcoded secret — and pass it once the code is fixed. The result is deterministic: the same rules run on every commit and return the same pass/fail, no matter which editor, AI agent, or teammate made the change.

Try it without installing

Not ready to touch your repo? The demo needs no setup and no git — it shows becwright blocking a sample bad commit and cleans up after itself:

npx becwright demo

Install

Pick your ecosystem. The npm and pnpm packages ship a self-contained binary, so no Python is required:

npm install --save-dev becwright    # or global: npm install -g becwright

pnpm add -D becwright

pipx install becwright              # or: pip install becwright

The npm packages cover linux-x64, linux-arm64, darwin-x64, darwin-arm64 and win32-x64. On any other platform, use the pipx route.

Scaffold rules and the hook

One command inside your repo:

becwright init

init detects whether the repo has Python or JS/TS files, writes a starter .bec/rules.yaml with matching rules, and installs the native git pre-commit hook. From this moment, every git commit runs the checks — no matter which editor, agent, or human makes it. (Prefer to wire things by hand? becwright install sets up just the hook, and you write .bec/rules.yaml yourself.)

Review the generated rules, then see where the repo stands right now:

becwright check --all    # run every rule over the whole repo

Plain becwright check (what the hook runs) looks only at the staged files — the exact set the next commit will create — which is why it stays fast even on large repos. --all scans everything git tracks.

See it block a commit

Say a file sneaks a live API key into the diff. Stage it and commit:

$ git add src/config.ts
$ git commit -m "add payments client"

✗ hardcoded-secrets  [blocking]
  intent: No credentials, API keys or passwords in source code.
  why it matters: A secret committed to git history stays leaked
  even after you delete it from the file.
  Found in:
    src/config.ts:3
      > const STRIPE_KEY = "sk_live_51H8..."

Commit blocked — 1 blocking rule failed (exit 1).

The commit never happened: the hook exited 1, so git refused it, and the output tells you (or your agent) exactly what the rule demands and why it exists. Fix the code — read the key from the environment instead:

const STRIPE_KEY = process.env.STRIPE_KEY;

Stage and commit again:

$ git add src/config.ts
$ git commit -m "add payments client"
✓ all rules passed — commit created

That’s the whole loop. Exit codes are stable and script-friendly: 0 pass, 1 a blocking rule failed, 2 not a git repo or usage error. Rules marked severity: warning print but don’t block. And if an AI agent made the bad commit, the same output — or becwright check --json — gives it the intent and the reason, so it can fix the code and retry on its own.

Next steps

• Write your own rules — or lean on the built-in forbid check for any “this pattern must not appear” rule — in Writing checks.
• Let Claude Code, Cursor, or any MCP-capable agent install and drive becwright for you in AI agents.
• Already using the pre-commit framework? They complement each other — see becwright vs pre-commit.