How LintCat works

How a review works

• Read. The reviewer starts from the diff, then opens the surrounding code, the previous version of each file, the files that import it and the tests that cover it.
• Propose. It returns candidate findings, each tied to a file, a line and, where it can, a fix.
• Check. LintCat drops anything that doesn’t point at a line you changed, isn’t confident enough or repeats another finding, removes any cited example of your conventions that doesn’t exist, and checks every fix against the current file.
• Post. What survives becomes inline comments, the AI PR Review check run and the review on your dashboard.

After the first review, a new push is reviewed from the commits added since, and findings nobody has resolved stay listed on the check run.

What it looks for

Drift: places where a change departs from how the rest of your repository already does the same thing. The code may work; the next reader now finds two conventions where there was one.

• Naming: a function, type, file or export named differently from how its neighbours name the same kind of thing.
• Patterns: a helper written again when the repository already has one, a layer the other files go through and this one skips.
• Style: export style, error shapes or module layout the neighbouring files share and no formatter or linter enforces.
• Documentation: a README, doc or comment the change made wrong, and a doc link the change adds to a file or heading that doesn’t exist. Broken links are found by LintCat itself, not the AI, so they need no cited examples. Rewording that makes a doc say less is not drift.
• Config: a setting or dependency added differently from the ones already there, such as an environment variable your .env.example and docs don’t list, or a second library for a job one you already use does.

Every finding cites at least two places in your existing code that show the convention, one line of your CLAUDE.md, AGENTS.md or CONTRIBUTING.md that states it, or a count of the neighbouring files that follow it, and each is checked before the finding posts. Where the existing files disagree among themselves and no rule doc settles it, there is no convention, and nothing is reported.

Bugs, security holes and performance problems are outside its scope, and so is anything your formatter, linter, typecheck or build already catches. The reviewer reads your lint and format configuration to know what that is.

Keeping the codebase in line

A diff only shows what changed. Before the reviewer starts, LintCat maps the repository’s imports, so for every changed file the reviewer already knows:

• what kind of file it is, and which package owns it;
• which test covers it, or that nothing does;
• how many files import it;
• whether it is dead, with nothing importing it and no entry point reaching it;
• whether it sits in an import cycle;
• which unchanged files sit beside it and play the same role: the local convention it is compared against;
• which conventions those files clearly share, counted rather than guessed: how they name files and tests, how they export, and how they import;
• which lines of your Markdown docs name something the change edits or removes;
• which new environment variables nothing documents, and which new dependencies duplicate one you already use;
• what your CLAUDE.md, AGENTS.md and CONTRIBUTING.md say, and which linter, formatter and typecheck settings apply to it, as they stand on your base branch.

It can also look up which files use a name, and which files have historically changed alongside this one. That is how it finds the helper the change wrote again, the convention three other files follow, and the doc that now describes something else.

How it's different

• Nothing unchecked reaches your pull request. Every finding and fix is checked before it posts. See Security.
• It can’t change your repository. The AI reviewer can only read. Comments, and fixes if you turn them on, are posted by LintCat after the checks.
• Fixes are proven, not guessed. A fix is only offered when the lines it replaces match the file exactly, so a suggestion never lands on the wrong code.
• The branch can’t mislead it. LintCat maps your repository as it was before the pull request, so a change can’t misrepresent the rest of your code.
• It never blocks a merge. The check run is advisory.
• Your model, nothing in CI. Install the GitHub App and add a model key. There is no workflow file to maintain.