interlint
v1.22.1
Published
Make your AI coding agent fix the rules it breaks before it moves on. Runs your existing ArchUnit, Checkstyle and PMD checks inside Claude Code and OpenCode.
Maintainers
Readme
Interlint runs the checks your project already has inside your AI agent's session. When the agent breaks a rule, it hears about it right away and fixes it before it moves on. Not in CI. Not by hand.
Works with Claude Code, GitHub Copilot, Codex and OpenCode, on Maven projects that use ArchUnit, Checkstyle, PMD, SpotBugs or JaCoCo coverage rules, and on TypeScript and JavaScript projects that use ESLint or dependency-cruiser architecture rules.
The agent puts infrastructure code in the domain. Interlint tells it right away, with the rule, the file and the line. The agent fixes it and carries on:
Why Interlint
- Your rules, enforced. Interlint has no rules of its own. It runs your ArchUnit tests, Checkstyle, PMD, SpotBugs, JaCoCo coverage rules, ESLint, dependency-cruiser and any command of yours, such as your tests, so your build stays the single source of truth.
- Fixed while the context is fresh. Checks run after edits, so the agent fixes a violation before it builds more code on top of it.
- No green, no done. At task end every check runs. The agent cannot finish while a rule is broken.
- One command to set up.
interlint initfinds your checks and wires your agent. - Know your agents. A metrics report shows which models follow your rules, and which rules they break most.
- Private by design. No telemetry, no account, no server, no network calls.
Know which agents follow your rules
Your team uses several models and agents. Which ones follow your rules? Which rules do they break most? Is it getting better?
interlint metrics report answers that in one report, with charts, ready to share with your team or a client.
The rules your agents break most. The top 20, by type: architecture, Checkstyle, PMD, SpotBugs and coverage. Fix the prompt, the AGENTS.md or the rule itself where it hurts most.
The models side by side. Failed checks by model, and violations per check run: the fair comparison, since a model you use more fails more often.
Week by week. Checks run and violations, to see whether your rules and prompts are working.
The report also shows how often each model tried to finish with a broken rule and fixed it in the same session, and how long your checks take.
interlint metrics report # Markdown, with charts GitHub draws
interlint metrics report --format html # one page that opens anywhere, offline
interlint metrics report --format pdf # a PDF to sendThe PDF is printed with the Chrome, Edge or Chromium you already have, so Interlint adds no dependency. For a quick look in the terminal, run interlint metrics. See Metrics for every option.
Quick start
Requires Node 22 or later and one of these:
- A Maven project with ArchUnit tests, or with Checkstyle, PMD, or a SpotBugs or JaCoCo
checkgoal in itspom.xml. - An npm project with ESLint in its
package.jsonand a flat configuration (eslint.config.*). - An npm project with dependency-cruiser in its
package.jsonand its configuration (.dependency-cruiser.*).
Install the CLI:
npm install -g interlintIn the root of your project, or of a workspace that holds several projects, set up your agent:
interlint init --agent claude-code # or: --agent copilot, --agent codex, --agent opencodeCommit the generated
interlint.yaml(and.claude/settings.json,.github/hooks/interlint.jsonor.opencode/), then start your agent as usual.To check that it all works, on any machine of the team:
interlint doctorIt names what is missing, such as a removed hook, a tool that is not installed or an old
interlint.yaml, and the command that fixes it.
[!IMPORTANT] On a Maven project, install
mvndtoo. It keeps Maven running between checks, which makes checks after each edit fast enough. Without it on yourPATH, every Maven check waits for task end, after the agent may have built more code on top of a broken rule. Interlint findsmvndon its own: there is nothing to configure.
How it works
| When | What runs | What the agent gets |
|---|---|---|
| After each edit | Checkstyle, ESLint and dependency-cruiser, with the failures of the changed files. ArchUnit, PMD and SpotBugs, which are slower, after 5 edited files or 200 written lines. The Maven checks need mvnd. | The violations, right away, in the same session. |
| At task end | Every check of the projects the agent changed, including the JaCoCo coverage rules of your pom.xml. | It cannot finish until everything is green. |
No endless loops. After 3 blocks in a row, Interlint lets the task end and shows you what is still failing.
No weakened rules. Before the agent edits a file that defines your rules, such as the ArchUnit test or checkstyle.xml, you are asked whether it may. A change you did not approve, even one made from the terminal, blocks the task end. See Protected files.
Make it fit your team
interlint.yaml decides when each check runs. init writes a starting point; the file is yours to edit, and you commit it so the whole team gets the same behavior.
| Field | What it does |
|---|---|
| when: edit | Runs after edits, and again at task end. |
| when: task-end | Runs only at task end. |
| every: <n> | With when: edit, waits until n distinct source files were edited. |
| lines: <n> | With when: edit, waits until n lines were written in its sources. |
| protected: | Paths and globs of the files the agent may change only with your approval. interlint.yaml always is. |
For example, to run ArchUnit once the agent has written 200 lines, so a log line in three files waits for task end but a new feature does not:
checks:
- name: architecture
run: ./mvnw -q test -Dtest=ArchitectureRulesTest -Dcheckstyle.skip -Dpmd.skip
report: archunit
when: edit
lines: 200With both every and lines, the check runs at whichever comes first. With neither, it runs after each edit. Whatever the setting, every check still runs at task end, so nothing is left unchecked. init never overwrites your edited interlint.yaml unless you pass --force.
See Every N files or lines for the full rules, and Using Interlint for every field, such as run, report and dir.
Built for teams
- The same checks for everyone.
interlint.yamland the agent setup live in the repository, so every developer and every agent runs the same rules.interlint doctortells each developer whether it works on their machine. - Deterministic. Your own build decides, not a prompt the agent may ignore.
- Your data never leaves your machine. Metrics are plain files in your user's state directory, never in the project. They keep only the check, its result and time, the rule, type and file of each violation, and the agent, model and session. Never your code, the violation messages or anything personal. To keep none, set
metrics: false. - No lock-in. Interlint adds no rules. Remove it, and your checks still run in your build and CI as before.
- Windows, Linux and macOS. CI tests every change on all three.
- Open source. MIT licensed.
Supported today
| | |
|---|---|
| Agents | Claude Code, GitHub Copilot (hooks in preview), Codex, OpenCode V2 |
| Checks | ArchUnit, Checkstyle, PMD, SpotBugs, JaCoCo coverage rules (at task end), ESLint, dependency-cruiser, and any command, such as your tests or tsc --noEmit |
| Build | Maven, with or without the Maven Wrapper, and mvnd for checks after each edit; npm with the project's own ESLint and dependency-cruiser |
| Layout | One project, a multi-module reactor, or a workspace of several Maven and npm projects |
Known limits:
- Only Maven projects and npm projects with ESLint or dependency-cruiser. On npm projects
initwrites no test,tscor coverage check: add your tests ortsc --noEmitas a command check. In a monorepo whose root has ESLint,initwrites one check for the root and does not look for a configuration in each package. Below a root with dependency-cruiser alone, it still writes each package's ESLint check. initfinds ESLint only with its flat configuration (eslint.config.*). With.eslintrc, write the check yourself.- dependency-cruiser 18 does not support TypeScript 7 yet. With it, the
depcruisecheck blocks and says it analyzed no source: use TypeScript 5. - PMD and SpotBugs cannot be limited to one file from the command line, so they check the whole project each time they run.
initgives themevery: 5andlines: 200, so they wait for 5 edited files or 200 written lines and shows the failures of all of them.
Documentation
- Using Interlint:
init,interlint.yaml,check,metricsand exit codes. - Claude Code: the hooks, their exit codes, the retry limit and subagents.
- GitHub Copilot: the hooks, trusting the folder, and what was tested.
- Codex: the hooks and trusting them.
- OpenCode: the plugin, what it does after edits and at turn end, and subagents.
- Development: building, testing and packing Interlint.
