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

If a hook manager already owns your hooks — Husky, the pre-commit framework, or a custom core.hooksPath — init won’t clobber it. It skips installing its own hook and prints the exact line to add to that manager instead, so becwright coexists with your existing setup.

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.

Want to confirm everything is wired correctly? becwright doctor diagnoses the setup — rules file, checks, hooks, and any hook manager it detected.

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.