Get Started
DocsTrack 1overview
/llms.txt
Core Mental Model3 min readbrevio-core v0.11.1

What is Brevio? (Plain English & Architecture Overview)

Plain-English Summary (For Anyone)

Pull-request checks for the mistakes coding agents repeat, plus an optional autonomous harness

brevio-core catches the mistakes coding agents repeat before they merge. It is a pull-request gate with no model call and no API key: it reads the lines a change adds and checks them against fixed rules. The Brevio Harness is a separate, commercial product that runs autonomous delivery on your own server.

Why this matters:
Coding agents write code that looks valid and still carries repeat mistakes: an as any cast, a silenced type error, an empty catch, a hardcoded key, a sleep in a test.
These are easy to see in one line and easy to miss in a long diff. A fixed rule gives the same finding for the same line on any machine.
brevio-core sits beside your linter, type checker and code scanner. It does not replace them.
When to use:Read this first to see where brevio-core fits: the agent's own edit loop, your pre-commit step and your pull request.
Technical Contract (For Engineers)
Line-level rules
CLI Invocation Signature:
brevio-core --version && brevio-core --help
Latency / Execution
Reads only the added lines with scan --diff; timing is not measured for 0.11.1
Token Cost
No model call. No API key.
Exit Codes
0 = success or nothing found; 1 = findings; 2 = usage error
Artifacts & Files Generated:
brevio-core.toml.brevio/baseline.json.brevio/guards.json.agents/rules/
Visual Execution Pipeline
5-Stage Progressive Flow
01No model call
Connect
Detect the stack and write CLAUDE.md, CONSTITUTION.md and roadmap.json
02Local
Plan
Write .brevio/task_plan.json from a PageRank repository map
03Fixers
Build
Prepare the task and apply the deterministic fixes
04Exit 1 on findings
QA
Run the single-task pre-PR gates and count findings
05Markdown
PR
Write .brevio/PR_BODY.md from what the gates found

What Brevio Is (and What It Isn't)

In Plain English:Think of brevio-core as a checklist that reads your diff. It doesn't replace your compiler or linter; it looks for the specific traps that coding agents fall into.
brevio-core is a Python package with no runtime dependencies (standard library only, Python 3.10 or newer). It documents 129 rules. `brevio-core scan` checks 14 of them on the lines a change adds, and `scan --surface` checks 9 more. The rules are line-level pattern checks, not AST or dataflow analysis, and they are TypeScript and React first. The Brevio Harness is a separate commercial product that runs on your own server; it is not needed to use brevio-core.
Catching a Silent Type Cast
Flagged (Before)Exit 1
// src/users.ts: an agent silences the type checker with 'as any'
export function parseUserData(raw: unknown): UserPayload {
  return raw as any;
}
Fixed (After)Exit 0
// Validate the data instead of casting it
export function parseUserData(raw: unknown): UserPayload {
  return UserPayloadSchema.parse(raw);
}
Terminal Output:
brevio-core scan src/users.ts
src/users.ts:2: [R9.1] Untyped escape hatch `as any` or `z.any()` in production source
brevio-core: 1 finding(s) in 1 file(s), 0 baselined, 0 silenced

Where It Runs: The Agent Loop, Pre-Commit and the Pull Request

In Plain English:The same rules run in three places, so a mistake that slips past one can still be caught by the next.
1. In the agent's loop: `brevio-core hook install` wires a hook into Claude Code and Cursor that scans a file after each edit and the uncommitted changes when the agent is about to stop. 2. On the pull request: the GitHub Action `Brevio-Ventures/brevio-core@v0.11.1` scans the lines the change adds. 3. In the agent's instructions: `brevio-core init` adds a short block of rules to AGENTS.md. `scan`, the agent hook and the MCP server use no network and send nothing.

The 129 Rules: Scanned, Surface, Check and Documented

In Plain English:Not every rule is run by the scanner. Some are checked by other commands, and the rest are written down for authors, reviewers and agents.
The rules run from R1.1 to R20.5. 14 are checked by `scan`, 9 more by `scan --surface`, 5 (the test-custody rules R20.1 to R20.5, a preview) by `brevio-core check`, and the others are documented for review and for agents. Rule IDs are permanent. A rule marked preview reports and does not fail a scan. `brevio-core rules --scanned` lists the 14 that `scan` runs.

No Lock-In: Plain Files and Open Standards

In Plain English:Everything brevio-core writes is a plain text or JSON file in your repository, and `init --undo` takes back what init wrote.
brevio-core writes SARIF 2.1.0 (`scan --sarif FILE`) for GitHub code scanning, Markdown reports for pull requests, `.brevio/baseline.json`, `.brevio/guards.json` and `.agents/rules/` files. `brevio-core init --undo` removes what init wrote and what you have not changed since. It does not touch your application code. The package is licensed under Apache-2.0.

Interactive Rule Explorer

Explore the brevio-core rules and load their examples into the panel on the right.

129 / 129 rules