AI agents

becwright is built so an AI agent can set it up and run it for you. CLAUDE.md and .cursorrules ask an agent to behave; becwright is the deterministic net that checks the result on every commit. There are two ways to wire it into an agent — a dedicated Claude Code plugin, and a generic path that works with any agent that speaks MCP or can run a shell command.

Which agents work with becwright?

All of them — that is the design goal. The enforcement lives in a native git pre-commit hook, so the guarantee never depends on which agent (or human) is typing. What differs per agent is how comfortable driving becwright is:

Agent	Recommended path	What it gets
Claude Code	dedicated plugin	the becwright skill + the /becwright command (init · check · add · status)
Cursor	MCP server	structured tools: check, list_rules, list_checks, preview_rule, add_rule
Windsurf, opencode, other MCP clients	MCP server	the same structured MCP tools
Anything with a shell	plain CLI	becwright check --json and the rest of the commands

If your agent is not in the table, start from the bottom row: becwright is an ordinary CLI, so any agent that can run a shell command can drive it. The sections below walk through each path.

Claude Code (plugin)

Claude Code has a first-class plugin. Install it from the becwright marketplace:

/plugin marketplace add DataDave-Dev/becwright
/plugin install becwright@becwright

The first command registers the repo as a plugin marketplace; the second installs the plugin from it. It does not bundle becwright — it installs the published becwright package (npm / PyPI) into your project.

What you get:

• becwright skill — teaches the agent what becwright is, how to install it (npm/pnpm, no Python needed, or pipx), how to scaffold rules, and how to read and fix check output. The agent invokes it automatically when you ask for a guardrail, a pre-commit check, or a rule that “can’t be ignored”.
• /becwright command — a direct entry point:

Command	What it does
/becwright init	Install becwright and scaffold .bec/rules.yaml + hook
/becwright check	Run the rules and summarize PASS / WARN / ADVISORY / BLOCK
/becwright add <regex-or-url>	Add a forbid rule or import a BEC
/becwright status	Report install + hook + rule count

The Claude Code integration guide walks through the setup step by step.

Any MCP-capable agent

Cursor, Windsurf, opencode, and any other MCP client can consume becwright through its MCP server — no dedicated plugin required. Point the agent’s MCP config at the command:

{
  "mcpServers": {
    "becwright": {
      "command": "becwright",
      "args": ["mcp"]
    }
  }
}

This exposes becwright’s structured tools:

• check — run the rules and return a blocked flag plus a per-rule list of {id, severity, passed, intent, why_it_matters, output}.
• list_rules — the repo’s rules as decision records, meant to be read before writing code so the agent steers clear of a blocked commit.
• list_checks — the built-in checks an agent can build rules from.
• propose_rules_from_claude_md / preview_rule / add_rule — derive rules from the repo’s CLAUDE.md, dry-run a candidate, and add it (add_rule only previews unless called with confirm=true).

The MCP server ships with the Python package (pipx install "becwright[mcp]"). See MCP & JSON output for the tool schemas and JSON shape, and the Cursor integration guide for a concrete setup.

Any agent with a shell

You don’t need an integration at all. becwright is a plain CLI, so any agent that can run shell commands — including opencode — can drive it directly:

npm install --save-dev becwright   # no Python needed
npx becwright init                 # scaffold rules + pre-commit hook
npx becwright check --all          # run every rule over the repo
npx becwright check --json         # machine-readable results to parse

Beyond check, the same CLI gives an agent becwright why (read the rules’ intent before coding), becwright doctor (diagnose a broken setup), becwright validate (lint .bec/rules.yaml without running a check), becwright search / becwright add (install a BEC from the built-in catalog), and becwright run <check> (invoke a single built-in check).

Because the pre-commit hook is native, the checks run on every commit no matter which agent made the change — that is the whole point: the guarantee does not depend on the agent cooperating.

How does an agent react to a blocked commit?

This loop is what makes the integration useful in practice. Suppose the agent writes code, stages it, and commits:

1. The pre-commit hook runs becwright check over the staged files. A blocking rule fails, the commit is rejected, and the command exits with code 1.
2. The agent sees the failure and runs becwright check --json (or calls the MCP check tool, which returns the same summary) to get a machine-readable picture instead of colored terminal text.
3. Each failing entry carries the rule’s id, its intent (what the rule demands), its why_it_matters (the reasoning behind it), and an output field pointing at the offending file and line.
4. The agent reads intent and why_it_matters, fixes the code — not the rule — and stages the fix.
5. It retries the commit. When every blocking rule passes, becwright check exits 0 and the commit lands.

The two prose fields exist precisely for step 4. intent tells the agent what state the code must reach; why_it_matters explains the stakes, which steers the agent toward a real fix instead of a cosmetic workaround — removing the leaked token, say, rather than renaming the variable that tripped the check. See MCP & JSON output for the full JSON shape.

And when the agent cannot find a fix, the failure output is still a useful artifact to hand to a human: it names the rule, the reason, and the exact lines.

Why does deterministic output matter for agents?

Ask an agent whether it followed all your rules and it will usually say yes — but that is a self-report, and self-reports from a probabilistic model are exactly what CLAUDE.md and .cursorrules already rely on. Models drift, drop context mid-session, and occasionally declare success on work they never did. No amount of extra prose in an instruction file fixes that.

becwright sidesteps the problem by never asking. The check runs against the staged files and returns an exit code: 0 means the code satisfies the rules, 1 means a blocking rule failed. Same code in, same verdict out, whichever model produced the change and however it was prompted. The exit code — not the agent’s summary — is the ground truth.

That determinism pays off in three ways:

• No prompt can bypass it. The hook is native git; it runs even if the agent never read a single instruction file.
• Retries converge. Because a rule’s verdict never wobbles, an agent looping on “fix → re-check” chases a fixed target, not a moving one.
• Automation can branch on it. A script or CI job can gate on the exit code without parsing prose — the same property the MCP server and check --json build on.

If becwright isn’t set up in your repo yet, the Quickstart gets it guarded in three commands — and the agent can run those commands itself.