# Boffin

Boffin (npm `boffinit`) is a control layer that sits around a coding agent and tries to stop the failure where you ask for a 15-line fix and get a 500-line renovation. Before the edit it feeds the agent the architectural constraints that apply to the specific file being touched; after the edit it requires a check sized to the change. The README positions it against `AGENTS.md` — the distinction it draws is delivery, since a rules file ships one static block for the whole repository while Boffin selects per edit.

## How it is put together

Rules live in the repository as versioned markdown under `packs/`, and the packs are GPG-signed. Nothing is fetched or hidden at install time; you can read every rule before trusting it. The selection step, which decides which of those rules apply to the file in front of the agent, is the part called ParselFire Core, and the README does not describe the routing map — it links out to a separate engine document. So the mechanism that makes this different from a rules file is exactly the piece the landing README does not explain.

Three profiles tune cleanup ambition rather than correctness: `lite` favors the smallest useful change, `full` is the default, `max` applies the strongest cleanup pressure. There is no `off`. The claim is that all three keep the same early correctness stages and rejection rules — trust-boundary validation, data-loss prevention, security, accessibility — so the profile moves how aggressively the agent tidies, not the floor it must clear.

The behavioral rules it enforces are stated as things to stop for: merging what is actually a special case, blurring a sync/async boundary, moving state away from its owner, or turning a focused task into a tour of the codebase. Open-ended refactors get a read-only audit first and then one verified finding at a time; focused changes get the narrowest check that proves the edit. Where cleanup conflicts with an earlier correctness rule, correctness wins.

## Hosts

One npm package covers Cursor, Claude Code, Codex and OpenCode, plus portable adapters for anything that reads `AGENTS.md`, `CLAUDE.md` or workspace rules. Node.js 18 or newer.

```
/plugin marketplace add MicSm/boffin
/plugin install boffin@boffin
```

```
codex plugin marketplace add MicSm/boffin
codex plugin add boffin@boffin
```

Codex does not trust plugin hooks automatically — until you run `/hooks` once and trust them, the skills work but per-session activation stays off. On OpenCode the always-on guidance arrives through `opencode.json` pointing at `.boffin/AGENTS.md`, with `/boffin` and `/boffin-review` on demand. Uninstallers are per host (`npx boffinit cursor uninstall`), and shared `.boffin/packs` survives while another host still has it installed.

## Evidence

Three public case studies, each a guided refactor on real open-source code: DuckDB landed at `+17 / -17` with 2,104 assertions across 8 test files passing and distinct continuation and recovery paths preserved; FastAPI at `+16 / -33` with 49 tests passing and no public API change; LangChain preserved a sync/async boundary with 4 tests passing. The repo says plainly that these are reproducible case studies rather than a controlled A/B benchmark, which is the right label — three hand-picked refactors with small diffs show the tool can produce a tight change, not that it produces tighter changes than the same agent without it.

The author is also clear about what it is not: not a linter or CI gate, since it acts before and after the edit rather than at merge; not a sandbox or security tool, since it does not isolate processes or filter shell commands or restrict filesystem and network access; and not a replacement for tests or review, which stay authoritative.

## Where it sits

This is a harness-side answer to the complaint in [[why-software-factories-fail]], which argues that models erode maintainability because nothing in their training penalizes it. Boffin does not touch that, and by that argument it raises the floor — catching the load-bearing detail before it gets flattened — without moving the ceiling. [[constraint-decay-backend-agents]] is the closest measured version of the problem it targets, showing agents shedding assertion-pass points as structural constraints accumulate, and [[clean-code-coding-agents]] is the argument for why the constraints are worth stating at all. The per-edit routing is a narrower form of the scaffolding in [[scaffold-model-fit]]: taking over the decision the model handles worst instead of hoping a longer prompt covers it.

On [[toolbox/watchlist]] until the routing engine stops being a black box: ParselFire Core is what decides which constraints reach which edit, and the README does not describe it.

Repo: https://github.com/MicSm/boffin — 37 stars, MIT, first commit June 2026. The README is marketing-forward and the single-author, two-month-old project has no independent evaluation behind it.