Catches the mistakes coding agents repeat before they merge: a pull-request gate with no model call and no API key.
| In Plain English (For Anyone) | Technical Contract (For Engineers) |
|---|---|
What it does: Answers common questions about how brevio-core catches AI coding mistakes, why agents cannot bypass it, and how it fits alongside linters and CI.When to read it: When evaluating brevio-core for your repository or engineering team. |
Runtime: Python standard library (3.10, 3.11, 3.12, 3.13)Catalogue: 123 rules (13 scanned, 110 documented) Exit Codes: The exit code is 0 when nothing is found, 1 when not. |
Coding agents repeat the same mistakes: a silenced type error, an as any, an empty catch, a hardcoded key, a sleep
in a test. Each is easy to see in one line and easy to miss in a long diff. brevio-core checks the lines a change adds
for those mistakes, on the pull request and inside the agent’s own loop, and says what to do instead.
Because it has to run everywhere with nothing to install but itself. The package uses only the Python standard
library: no dependency tree to audit, no build step, no native code. Python is already on every CI runner and most
developer machines, and uvx brevio-core or the single-file .pyz from the release runs it without touching your
project’s own toolchain. The rules read text, so the language of the scanner does not limit the languages it reads.
A rule that reads one added line is fast, gives the same answer on every machine, explains itself in one sentence and never flags code that was already there. Most of the mistakes agents repeat are visible in one line. A mistake that needs the whole file, the types or the call graph is a job for your linter, your type checker or a code scanner, and brevio-core does not try to replace them.
No. A person can silence one finding with an ignore comment that gives a reason, in a scan they run themselves or in
CI. The agent hook and the MCP server never honour that comment, so an agent that adds one still sees the finding. A
diff scan reports every ignore comment, baseline entry and brevio-core.toml change the change adds as a new
suppression, which needs a person: the check stays red until a reviewer allows it with --allow-new-suppressions.
Changing what a rule flags is a code change to the rules, reviewed like any other.
scan, the agent hook and the MCP server use no network and send nothing. The rules make no model call and need no API
key. The security review page lists what each command reads and runs, and tests check it.
It sits beside them. A linter checks style and correctness in the language it knows; Semgrep matches patterns you write; CodeQL follows data through a program. brevio-core is narrower: a fixed set of rules picked from the mistakes coding agents repeat, run on the added lines only, with the same output in the agent’s loop as on the pull request. Several of its rules flag code that is valid to a linter. Keep your linter; add this for the agent mistakes.
A model-based reviewer reads the change and gives an opinion, which can differ from run to run and costs a model call. brevio-core gives the same finding for the same line every time, at no cost per run, and a finding can block a merge. The two do not exclude each other.
Every rule has a page with what it catches, why, a bad and a good example, and how it is checked. The
rule index marks which rules brevio-core scan runs.
The scan reads only the added lines, with fixed patterns, so it finishes quickly; most of a CI run is the checkout and the install. The agent hook gives up quietly when it runs past its time budget and lets the agent go on.
Open a “False positive” issue with the line and why it is correct. Until it is fixed, a person can silence that one finding with an ignore comment and a reason. A rule that fires wrongly too often is narrowed or retired; its ID is never reused.
The package is free and open source under Apache-2.0, and stays complete on its own. A paid service, planned and opt in, will sync learned guards and suppression approvals across repositories and teammates; it asks first and shows the exact files before anything leaves your machine.