# Using Interlint

How to set Interlint up in a project, what `interlint.yaml` holds and how the checks run. For the agent side, see [OpenCode](opencode.md) and [Claude Code](claude-code.md).

## Install

Requires Node 22 or later.

```bash
npm install -g interlint
```

`interlint` is then on your `PATH`, where the OpenCode plugin and the Claude Code hooks look for it. To run a build of this repository instead, see [Development](development.md).

To see which version is installed:

```bash
interlint --version
```

## `interlint init`

Run it in the root of your Maven or npm project, or of a workspace that holds several (see [Multi-module projects and workspaces](#multi-module-projects-and-workspaces)), with the agent you use (`opencode` or `claude-code`):

```bash
interlint init --agent opencode
```

`init` looks for the test classes under `src/test/java` that use `@ArchTest`, for `maven-checkstyle-plugin` and `maven-pmd-plugin` in the build of `pom.xml`, and for an execution of `spotbugs-maven-plugin` or `jacoco-maven-plugin` that runs its `check` goal. It writes an `interlint.yaml` with one check for each thing it finds:

```yaml
# Generated by interlint init.
checks:
  - name: architecture
    run: ./mvnw -q test -Dtest=ArchitectureRulesTest -Dcheckstyle.skip -Dpmd.skip
    report: archunit
    when: edit
    every: 5
    lines: 100
  - name: checkstyle
    run: ./mvnw -q checkstyle:check
    report: maven
    when: edit
  - name: pmd
    run: ./mvnw -q compile pmd:check -Dcheckstyle.skip
    report: maven
    when: edit
    every: 5
    lines: 100
```

- The checks use the project's Maven: `./mvnw` when the project has the Maven Wrapper, `mvn` otherwise. The file is the same on every machine, so commit it.
- Every check runs after edits when `mvnd` is on the `PATH`, and at task end without it (see [After each edit](#after-each-edit)). `checkstyle` checks only the changed files, so it runs after each edit. `architecture` and `pmd` run after 5 edited files or 100 written lines, whichever comes first, with [`every: 5` and `lines: 100`](#every-n-files-or-lines): ArchUnit builds the project and PMD analyses all of it, which in a large project takes tens of seconds. A few small edits, such as a log line in three files, wait for task end. `init` says which applies on yours. To run them after each edit, remove `every` and `lines`; to wait only for written lines, whatever the number of files, remove `every`; to wait for more, raise them; to leave them to task end, set their `when` to `task-end`.
- It never replaces a different `interlint.yaml` unless you pass `--force`. Without `--agent` it then writes nothing and exits with 2. With `--agent` it keeps your `interlint.yaml`, lists it under `Kept:`, and still writes or updates the agent's files, so you can update them after editing the config. Running it again on an unchanged project changes nothing.
- The `architecture` check runs only the `@ArchTest` classes. `checkstyle`, `pmd` and `spotbugs` run the project's own `check` goals, each in its own Maven call: in one call, a failing goal stops the ones after it. `pmd` and `spotbugs` compile first: PMD resolves types from the compiled classes, and SpotBugs analyses them. See [Checkstyle and PMD](#checkstyle-and-pmd) and [SpotBugs](#spotbugs).
- Each check skips the plugins the other checks run (`-Dcheckstyle.skip`, `-Dpmd.skip`, `-Dspotbugs.skip`), so a failure shows in one check only. Without that, a build that binds `checkstyle:check` to an early phase such as `validate` would stop `test` and `compile` before ArchUnit, PMD or SpotBugs run, and show Checkstyle's failures under their names. A check skips only the plugins the build has: without Checkstyle, PMD or SpotBugs in the build, the `architecture` check has no `-D…skip`.
- When the build runs a plugin's `check` goal in an `<execution>`, the check names that execution, as in `checkstyle:check@style`, so the configuration inside it applies: called plainly, Maven runs the goal with the plugin's defaults. An execution without `<id>` is `default`; one turned off with `<phase>none</phase>` is left out.
- A plugin counts when it is in `<build>`, in `<plugins>` or `<pluginManagement>`. Plugins only in a comment, a `<profile>`, `<reporting>`, `<dependencies>` or `<dependencyManagement>` are left out, and so are plugins declared only in an external parent. A Checkstyle or PMD plugin with executions counts only when one of them runs `check`: one whose executions only write a report (the `checkstyle` or `pmd` goal) or run `cpd-check` gets no check, as the build does not enforce its rules. A plugin without executions counts, as you run its `check` goal yourself. In a project with modules, see [Multi-module projects and workspaces](#multi-module-projects-and-workspaces).
- When the build runs `spotbugs:check`, it adds a `spotbugs` check that runs after 5 edited files or 100 written lines, as `pmd`. A SpotBugs plugin without an execution that runs `check` gets no check: the build only uses it for reports. See [SpotBugs](#spotbugs).
- When the build runs `jacoco:check`, it adds a `coverage` check that runs at task end only. See [JaCoCo coverage](#jacoco-coverage).
- In an npm project with ESLint, it writes an `eslint` check that runs after each edit. See [ESLint](#eslint).
- In an npm project with dependency-cruiser, it writes a `depcruise` check that runs after each edit. See [dependency-cruiser](#dependency-cruiser).
- It lists the files that define your rules under `protected:`: the `@ArchTest` classes, the rule files the build's Checkstyle, PMD and SpotBugs settings name (`configLocation`, `suppressionsLocation`, `ruleset`, `excludeFilterFile`, `includeFilterFile`) when the project holds them, and the ESLint and dependency-cruiser configuration. `pom.xml` and `package.json` stay out. See [Protected files](#protected-files).
- With no `@ArchTest` classes, no Checkstyle or PMD plugin, no SpotBugs or JaCoCo `check` goal and no npm project with ESLint or dependency-cruiser it says so, writes nothing and exits with 2.
- `--agent opencode` also copies the OpenCode plugin. See [OpenCode](opencode.md).
- `--agent claude-code` also adds Interlint's hooks to `.claude/settings.json`. See [Claude Code](claude-code.md).
- `--agent copilot` also writes Interlint's hooks to `.github/hooks/interlint.json`. See [GitHub Copilot](copilot.md).
- `--agent codex` also adds Interlint's hooks to `.codex/hooks.json`, and reminds you to trust them in Codex. See [Codex](codex.md).
- At the end it prints what it detected and which files it wrote, left unchanged or kept. `--cwd <dir>` runs it on another directory.

The generated file is yours: edit it to change `when` or the command.

## `interlint check`

Run the checks by hand:

```bash
interlint check --when task-end
```

When every check passes it exits with 0 and prints one line with the checks that ran and how long each took:

```text
✓ Interlint · checks passed: checkstyle (1.2s), architecture (4.3s)
```

A check that passed on [the reports of the agent's own build](#reports-from-the-agents-own-build) shows `in the last build` instead. When no check runs, it prints nothing.

When a check fails, it prints each violated rule, with the text of its `because()` and every violation with its source file and line:

```text
✗ architecture · ARCH-01: domain depends on nothing outside domain

  Method <com.acme.domain.Order.toEntity()> calls constructor <com.acme.infra.OrderEntity.<init>()> in (Order.java:27)
    at src/main/java/com/acme/domain/Order.java:27

Fix these problems before continuing.
```

| Exit code | Meaning |
|---|---|
| 0 | Every check passed |
| 1 | A check failed: violations, a command that failed without leaving any, an ArchUnit command that wrote no report, or broken compiled classes |
| 2 | Configuration or usage error, or an unexpected Interlint error |

### Broken compiled classes

An IDE that builds automatically, such as VS Code with the Java extension or Eclipse, compiles into the same `target/classes` as Maven. If it writes there while a check runs, ArchUnit reads classes compiled with unresolved types and reports violations the code does not have: a domain class that depends on `<ProjectName>`, a service that implements no port. The types are named without a package, which `javac` never compiles. When a violation names one, Interlint shows no violation of that check and says the build is broken instead:

```text
✗ architecture · the compiled classes are broken, so its ArchUnit violations are not shown

  The report names types without a package: <ProjectName>, <ProjectStatus>.
  javac never compiles a class like that. An IDE building automatically wrote to target/ while the check
  ran. Do not change the code for these violations: check again.
```

You do not need to close the IDE, turn off its automatic build or build with `clean`.

Maven does not recompile those classes by itself, since they are newer than their sources. So before every check that runs Maven, Interlint deletes the classes in `target/classes` and `target/test-classes`, in the project and its modules, that the IDE compiled with errors: those that contain `Unresolved compilation problem`, which the Eclipse compiler writes and `javac` never does. Maven then compiles them again. If the check fails and the IDE wrote more of them while it ran, Interlint deletes them and runs the check once more, and shows that second run. A rule that analyzes classes of the default package would show the same message, since their names have no package either.

### FreezingArchRule store frozen from broken classes

A `FreezingArchRule` store records the violations a team accepted. If ArchUnit created or updated it while the classes were broken, it saved them with types without a package. ArchUnit compares violations with the store as text, so once the classes are sound again those violations look new, and the agent would get violations it is not meant to fix.

Interlint reads the store of the project and of each module: the `freeze.store.default.path` of its `src/test/resources/archunit.properties`, or `archunit_store`. When the store holds violations that name types without a package, Interlint leaves out the reported violations that match them, ignoring packages, line numbers and lambda numbers. A check that failed only on those passes; if Maven also failed for another reason, such as a module that does not compile, it still fails. Then it prints a notice for you, after the failures, if any:

```text
ℹ Interlint · for the user: the ArchUnit store archunit_store was frozen from broken compiled classes

  It names types without a package: <Order>. Its frozen violations no longer match
  the code, so ArchUnit reports them as new. Interlint did not show the agent 1 of them.
  Refreeze it from a clean build: ./mvnw clean test -Darchunit.freeze.refreeze=true
  Agent: do not change the code for this. Tell the user.
```

The notice does not change the exit code. Each agent shows it to you at task end: Claude Code as a message for you (see [Claude Code](claude-code.md#what-the-hooks-do)), OpenCode as a message in the session that does not make the agent continue (see [OpenCode](opencode.md#when-a-turn-ends)).

On Windows, a leading `./` in `run` becomes `.\`, so the same `interlint.yaml` works on every operating system.

## `interlint doctor`

Tell whether Interlint works in this project and on this machine, and what to fix if not:

```bash
interlint doctor [--cwd <dir>]
```

It only reads: it writes no file and runs no check. It looks at:

| Section | What it checks |
|---|---|
| Environment | Node is 22 or later, the version of Interlint, and, when an agent is set up, that `interlint` is on the `PATH`, since the agent's hooks run it |
| Configuration | `interlint.yaml` exists, is valid, and the `dir` of each check exists |
| Tools | The program each check runs is found from its directory, as the check would run it: `./mvnw` or `mvn` (or `mvnd`, which runs every Maven check when it is on the `PATH`), and for `npx`, its package or executable installed in a `node_modules`, from the check's directory up. An `interlint.yaml` that is there but cannot be read is an error of its own, so `doctor` never suggests replacing it with `init`. Without `mvnd`, the Maven edit checks run at task end: a warning |
| Agents | The files of each agent set up in the project are what `interlint init` writes with this version: `.claude/settings.json`, `.opencode/plugins/interlint/`, `.github/hooks/interlint.json` and `.codex/hooks.json`. A file with no Interlint hooks is a warning; Interlint's files missing or from another version are an error, and so is having no agent set up |
| State | Interlint can write its state and metrics directory |
| Protected files | Each pattern of `protected:` matches a file. One that matches none is a warning |

Each line is correct (`✓`), a warning (`!`) or an error (`✗`), and a warning or an error comes with what fixes it:

```text
Interlint doctor in /home/me/shop

Environment
  ✓ Node 22.11.0
  ✓ Interlint 1.18.0
  ✓ interlint is on the PATH, where the agent's hooks run it
Configuration
  ✓ interlint.yaml is valid, with 3 checks
Tools
  ✓ check architecture: ./mvnw is found
  ✓ check checkstyle: ./mvnw is found
  ✓ check pmd: ./mvnw is found
  ! mvnd is not on the PATH, so the Maven edit checks run at task end
    → install mvnd to run them after edits
Agents
  ✗ Claude Code: .claude/settings.json is missing or from another version of Interlint
    → run `interlint init --agent claude-code`
State
  ✓ /home/me/.local/state/interlint can be written, for the state and the metrics
Protected files
  ✓ 2 patterns of protected match 3 files

1 error, 1 warning.
```

| Exit code | Meaning |
|---|---|
| 0 | No error. There may be warnings |
| 1 | At least one error |
| 2 | Usage error, such as a `--cwd` that does not exist |

## Checkstyle and PMD

A check with `report: maven` reads the reports Checkstyle and PMD write in `target/`: `checkstyle-result.xml` and `pmd.xml`, in the project and in its modules, at any depth. Each violated rule shows its message and source file and line, like an ArchUnit rule:

```text
✗ checkstyle · LineLength

  Line is longer than 80 characters (found 87).
    at src/main/java/com/acme/domain/Order.java:8

Fix these problems before continuing.
```

- The project's build decides, not Interlint. The reports also list what the build accepts, such as warnings under Checkstyle's `violationSeverity` or violations under PMD's `failurePriority`. So a `report: maven` check fails only when Maven fails. When Maven exits 0 it passes, with or without a report: the build may skip the plugin, for example with `<skip>true</skip>` outside CI.
- When Maven fails, only the most severe level in the reports is shown: Checkstyle `error` before `warning` and `info`, the lowest PMD `priority` number first. That level always failed the build, so nothing the build accepts is shown. Less severe failures, if any, show on the next run.
- A report counts only when Maven says its plugin's `check` goal failed. When Maven fails for another reason, such as code that does not compile, the check shows the last lines of Maven's output instead.
- Messages are in the language of the JVM, as Checkstyle and PMD write them.

## SpotBugs

SpotBugs also uses `report: maven`. The check reads `target/spotbugsXml.xml`, in the project and in its modules, and shows each bug type with its message and source file and line:

```yaml
  - name: spotbugs
    run: ./mvnw -q compile spotbugs:check@spotbugs -Dcheckstyle.skip -Dpmd.skip
    report: maven
    when: edit
    every: 5
    lines: 100
```

```text
✗ spotbugs · COMMAND_INJECTION

  This usage of java/lang/Runtime.exec(Ljava/lang/String;)Ljava/lang/Process; can be vulnerable to Command Injection
    at src/main/java/com/acme/domain/TokenMaker.java:19

Fix these problems before continuing.
```

- It works as with Checkstyle and PMD: the check fails only when Maven fails, and then shows only the most severe `priority` in the report. Bugs under the build's `failThreshold` are in the report but never shown. Bugs left out by `threshold` or by the build's include and exclude filters are not in the report at all.
- SpotBugs analyses compiled classes, so the check runs `compile` first. Without it, `spotbugs:check` finds no classes and passes.
- SpotBugs plugins, such as Find Security Bugs, write their bugs into the same report.
- SpotBugs names each source by its path below a source directory. Interlint finds the file in the source directories the report lists, such as `src/main/java` or `target/generated-sources/annotations`, or in the module's `src/main/java` when it lists none and the file is there; otherwise the bug shows without a path. A bug about a whole class or field, such as a serialization bug, shows the line of that field, method or class.
- SpotBugs cannot be limited to one file from the command line here, so, as PMD, it analyses the whole project each time and an `edit` check shows only the failures of the changed files.

## JaCoCo coverage

A check with `report: jacoco` blocks the end of the task while the build breaks a coverage rule of `jacoco-maven-plugin`, the `<rules>` of its `check` goal. `init` writes it when the build has an execution that runs that goal:

```yaml
  - name: coverage
    run: ./mvnw test jacoco:check@check -fae -Djacoco.append=false -Dcheckstyle.skip -Dpmd.skip
    report: jacoco
    when: task-end
```

Each broken rule shows what it limits, the element JaCoCo measured, its value and the minimum or maximum, as JaCoCo prints it. A rule on a class also shows the class's source:

```text
✗ coverage · lines covered ratio of each bundle: minimum 0.80

  Rule violated for bundle core: lines covered ratio is 0.50, but expected minimum is 0.80

✗ coverage · branches covered ratio of each class: minimum 0.50

  Rule violated for class demo.Calc: branches covered ratio is 0.00, but expected minimum is 0.50
    at core/src/main/java/demo/Calc.java

  To see which classes lack tests, run ./mvnw jacoco:report and read target/site/jacoco/jacoco.csv in each module.

Fix these problems before continuing.
```

- JaCoCo writes its broken rules only to Maven's output, not to a report. The check reads them from there, so its command must not use `-q`: Maven hides them with it, and the check then says so.
- It runs only at task end. Coverage needs the whole test suite, and a rule covers a whole module, a package or a class, not the file an edit changed. `interlint.yaml` rejects a `report: jacoco` check with `when: edit`.
- `test` runs the tests and stops before `verify`, where the build runs `jacoco:check` again. Naming the execution, as in `jacoco:check@check`, applies its rules: called plainly, the goal has none.
- `-fae` builds every module it can after one fails, so each module with broken rules shows them. A module that depends on a failed one is skipped.
- `-Djacoco.append=false` starts the coverage data of each module afresh. Without it, JaCoCo adds each run to the data of earlier ones, and tests the agent deleted would still count. If your Surefire runs tests in several JVMs at once (`forkCount` above 1), they would overwrite each other's data: replace it with `clean` in the command.
- When Maven also fails for another reason, such as a failing test or a module that does not compile, the check shows the last lines of Maven's output instead of the coverage rules.
- The build decides, as with Checkstyle and PMD: a broken rule counts only when JaCoCo fails the build. With `<haltOnFailure>false</haltOnFailure>` JaCoCo prints the rule and the build goes on, so the check passes.
- When Maven exits 0 but JaCoCo checked no rule, as with `-Djacoco.skip` or without execution data, the check fails: nothing proves the coverage is met.
- With `--changed`, a build the agent ran since its last change, such as `mvn clean install`, spares the tests: Interlint runs only the command's `jacoco:check` goals on the coverage data that build left, in a second or two, and the check passes "in the last build" when every rule is met. See [Reports from the agent's own build](#reports-from-the-agents-own-build).

## ESLint

A check with `report: eslint` runs the project's own ESLint, with its configuration, and reads its JSON report. `init` writes it for an npm project that lists `eslint` in the `dependencies` or `devDependencies` of its `package.json` and has a flat configuration file (`eslint.config.js`, `.mjs`, `.cjs`, `.ts`, `.mts` or `.cts`):

```yaml
checks:
  - name: eslint
    run: npx --no -- eslint -f json -o node_modules/.cache/interlint/eslint.json .
    report: eslint
    when: edit
```

Each broken rule shows its message, file and line, like a Checkstyle rule:

```text
✗ eslint · @typescript-eslint/no-explicit-any

  Unexpected any. Specify a different type.
    at src/orders/order.ts:1

Fix these problems before continuing.
```

- The report must go to `node_modules/.cache/interlint/eslint.json`, relative to the directory the check runs in, with `-f json -o`: that is where Interlint reads it. It is outside git, and ESLint creates the directory.
- `npx --no` runs the ESLint installed in the project and never downloads one. Keep the `--`: without it, npx takes `-f` for itself.
- Your ESLint configuration decides, not Interlint. The check fails only when ESLint fails. A warning your project accepts does not block and is not shown. When ESLint fails with errors, only the errors are shown. When it fails on warnings alone, as with `--max-warnings 0`, the warnings are shown.
- An error without a rule, such as a file ESLint cannot parse, shows under `ESLint` with its file and line.
- When ESLint fails before it checks any file, as with a broken configuration or without `node_modules`, the check shows the last lines of its output instead, and still blocks.
- The check needs no `mvnd`. After an edit, the ` .` at the end of the command is replaced with the edited files, so ESLint checks only them, and only their failures are shown. With a flat configuration the command also gets `--no-warn-ignored`, so editing a file ESLint ignores does not fail under `--max-warnings 0`.
- After an edit, ESLint checks the whole project, and still shows only the failures of the edited files, when the command does not end with ` .` (such as `npm run lint -- …`), when it is more than one program (`&&`, `|`, `>`…), when more than 50 files are pending, or when a path has characters other than ASCII letters, digits, `_`, `.`, `-`, `/`, `@` and `+` (such as `[id].tsx`). When another file then has errors, a warning in the edited file that fails `--max-warnings` shows at task end, not after the edit.
- With the older configuration (`.eslintrc*`), `init` writes no check. Write it yourself, and name the extensions as that ESLint needs: `npx --no -- eslint --ext .ts -f json -o node_modules/.cache/interlint/eslint.json .`
- `init` looks for npm projects with ESLint in the root and, when the root is not one, up to three levels below it, skipping `node_modules`, `dist`, `build` and `coverage`. In a monorepo whose root has ESLint it writes one check for the root and does not look for a configuration in each package: add those checks yourself, each with its `dir`.
- A `package.json` that is not valid JSON next to an ESLint configuration is not a project for `init`. When it then finds nothing to check, it names that file.
- Not checked yet on npm projects: `tsc` and coverage.

## dependency-cruiser

A check with `report: depcruise` runs the project's own [dependency-cruiser](https://github.com/sverweij/dependency-cruiser), with its rules, and reads its JSON report. It is the architecture check of a TypeScript or JavaScript project, as ArchUnit is in a Maven one. `init` writes it for an npm project that lists `dependency-cruiser` in the `dependencies` or `devDependencies` of its `package.json` and has a configuration file (`.dependency-cruiser.js`, `.cjs`, `.mjs`, `.ts`, `.cts`, `.mts` or `.json`):

```yaml
checks:
  - name: depcruise
    run: npx --no -- depcruise . -T json --output-to node_modules/.cache/interlint/depcruise.json
    report: depcruise
    when: edit
```

Each forbidden dependency shows its rule, with the rule's `comment` when it has one, the file that imports and the module it imports:

```text
✗ depcruise · domain-not-to-infrastructure: domain must not depend on infrastructure

  src/domain/order.ts depends on src/infrastructure/order-repository.ts
    at src/domain/order.ts

Fix these problems before continuing.
```

- The report must go to `node_modules/.cache/interlint/depcruise.json`, relative to the directory the check runs in, with `-T json --output-to`: that is where Interlint reads it. dependency-cruiser does not create the directory, so Interlint creates it before the check runs, even in a package whose dependencies an npm workspace keeps in the root's `node_modules`. It also deletes the report of the previous run, so the one it reads is always new.
- `npx --no` runs the dependency-cruiser installed in the project and never downloads one.
- Your rules decide, not Interlint. Interlint has none of its own: write them in your configuration, for example from the layers your `AGENTS.md` describes. Only violations of severity `error` block. Those of severity `warn` or `info` do not block and are not shown.
- dependency-cruiser gives no line number, so a violation shows its file alone. A rule about a module, such as `no-orphans`, shows the module. A cycle shows its path. The paths in the message are relative to the check's `dir`; the `at` line is relative to `interlint.yaml`.
- When dependency-cruiser fails, as with a broken configuration or without `node_modules`, the check shows the last lines of its output instead, and still blocks.
- dependency-cruiser 18 does not support TypeScript 7 yet. With it, dependency-cruiser leaves out the TypeScript files and finds nothing. The check then blocks and says `dependency-cruiser analyzed no source: it found no module, or no TypeScript compiler it supports`. Install TypeScript 5 in the project (`npm install --save-dev typescript@5`).
- The check needs no `mvnd`. After an edit, dependency-cruiser still analyzes the whole project, since a rule about who imports a file needs all of it, and only the violations of the edited files are shown: those whose importing file is one of them, and the cycles that go through one of them. Task end shows the rest, such as a module an edit left orphaned.
- dependency-cruiser analyzes the whole project after each edit, which takes longer as the project grows: about 2 seconds on a small one. When it slows the agent down, give the check [`every` or `lines`](#every-n-files-or-lines), as `init` does for PMD.
- `init` looks for npm projects with dependency-cruiser as it does for ESLint. A project with both gets both checks, such as `eslint` and `depcruise`. Below a project with dependency-cruiser alone, such as the root of a monorepo, `init` still looks for packages with ESLint and writes their `eslint` checks. They get no `depcruise` check of their own, since the one above already analyzes them.

## Any command

A check with `report: exit-code` runs any command of your team, such as your tests or `tsc --noEmit`, and reads only its exit code. It reads no report. 0 passes; any other code fails, and the agent cannot end the task:

```yaml
checks:
  - name: tests
    run: npm test
    report: exit-code
    when: task-end
  - name: types
    run: npx --no -- tsc --noEmit
    report: exit-code
    when: task-end
```

A failure shows the check, the exit code and the last lines of the command's output:

```text
✗ tests · the command failed (exit code 1)

  Command: npm test
  Last lines of its output:
     FAIL  test/order.test.ts > totals
    AssertionError: expected 4 to be 3
    …
```

- The agent gets the last 60 lines of the output, enough for two or three failing tests of Vitest or Jest, or Maven's test results. When the output is longer, its first line says how many earlier lines were cut, such as `… 40 earlier lines cut`.
- A command that does not exist or cannot start, such as a typo in `run`, does not count as a failure of the check. It says `the command did not run: it was not found or could not start`, with the last lines of its output, and still blocks. A command that starts but cannot find a tool it runs, such as `npm test` without its test runner installed, fails the check as usual, with that error in its output.
- `init` never writes this check: Interlint does not know your commands. Add it to `interlint.yaml` yourself.
- It works with `when`, `every`, `lines` and `dir`, like any check. At edit, any changed file inside its project counts as one of its sources, since Interlint cannot tell what the command checks.
- A slow command, such as a whole test suite, belongs in `when: task-end`. In `when: edit` it runs after each edit; give it [`every` or `lines`](#every-n-files-or-lines) if it must run there.
- At task end with `--changed`, it runs only when its project changed since its checks last passed, like every check. It has no report, so it never passes on [the reports of the agent's own build](#reports-from-the-agents-own-build).
- Its metrics keep one violation per failing run, with the check's name as its rule.

## After each edit

A check with `when: edit` also runs after the agent changes one of its sources:

```bash
interlint check --when edit --file src/main/java/shop/Order.java
```

- Only `edit` checks run, and only when a changed file inside the project is one of their sources: `*.java` for `report: archunit` and `report: maven`, and `*.ts`, `*.tsx`, `*.mts`, `*.cts`, `*.js`, `*.jsx`, `*.mjs` and `*.cjs` for `report: eslint` and `report: depcruise`, and any file for `report: exit-code`. A `report: jacoco` check never runs at edit. Any other file, such as `README.md`, runs nothing and exits with 0.
- The output and exit codes are the same as at task end. `--file` can be repeated.
- `--lines <n>` gives the lines the edit wrote in a file, for checks with [`lines`](#every-n-files-or-lines). Give one `--lines` after each `--file`, as in `--file A.java --lines 12 --file B.java --lines 0`, or none at all: files without it wrote no lines. The agent integrations always give it.
- With [`mvnd`](https://github.com/apache/maven-mvnd) on the `PATH`, a check whose `run` starts with `mvn`, `mvnw` or `./mvnw` runs with `mvnd` instead, with the same arguments, at edit time and at task end. Keep `./mvnw` in `interlint.yaml` so it works for teammates without `mvnd`.
- Without `mvnd`, Maven `edit` checks do not run after edits, because a cold Maven build takes several seconds; they still run at task end. Other `edit` checks, such as an [ESLint](#eslint) or [dependency-cruiser](#dependency-cruiser) check, run after edits with or without it.
- A `report: maven` check shows only the failures of the changed files: Checkstyle, PMD and SpotBugs rate each file on its own, so another file's failures are not the edit's, and task end shows them. When Maven failed only because of other files, the check passes after the edit. An ArchUnit check shows every failure, because an edit can break a rule in a class it did not change.
- A `run` with `checkstyle:check` gets `-Dcheckstyle.includes` with the changed files' paths from their source root, such as `shop/Order.java`, and `-Dcheckstyle.includeResources=false -Dcheckstyle.includeTestResources=false`, so Checkstyle checks only those files, still with the build's configuration. PMD and SpotBugs cannot be limited from the command line, so they check the whole project.
- Checkstyle also checks the whole project when the `run` sets `checkstyle.includes` itself or is more than one program (`&&`, `|`, `>`…), when a path is not plain ASCII, when a `pom.xml` of the project or `.mvn/maven.config` names `checkstyle.includes` (the `-D` would replace it, and the edit would check files the build never checks), or when the plugin's configuration in `pom.xml` sets `<includes>`, which Maven applies over `-D`.
- When Maven fails, only the most severe level in the whole report is shown, as at task end, and then only in the changed files. So when PMD also fails in another file at a more severe priority, a failure in the changed file shows at task end, not after the edit.
- Check runs on the same project never overlap: a second edit waits until the first one's checks finish.

### Every N files or lines

A slow `edit` check, such as ArchUnit or PMD in a large project, can wait for several edited files with `every`, for several written lines with `lines`, or for whichever comes first with both:

```yaml
checks:
  - name: checkstyle
    run: ./mvnw -q checkstyle:check
    report: maven
    when: edit
  - name: pmd
    run: ./mvnw -q pmd:check
    report: maven
    when: edit
    every: 5
    lines: 100
```

- The check runs after the edit that brings it to 5 distinct sources edited since it last passed, or to 100 lines written in them, and it runs on all of them: the failures of any of them are shown, not only those of the last one, and a Checkstyle check with `every` checks those files. The edits before it do not run the check. Checks without `every`, here `checkstyle`, still run after each edit.
- A Maven check with `every` still needs `mvnd` to run after edits. Without it, edits do not count and the check runs at task end.
- A file edited twice counts once for `every`, and its lines add up for `lines`. Files that are not sources of the check, such as `README.md`, do not count.
- The lines an edit wrote are those it adds or changes, not the ones it keeps around them and not the ones it removes: a log line added between two lines counts 1. Every line of a new or rewritten file counts, and so does each `+` line of an OpenCode patch.
- With `lines` and no `every`, the number of files does not matter: the check waits only for the lines. With `every` and no `lines`, lines do not matter.
- The count is kept per check, so for each project of a workspace, and is shared by the main agent and its subagents.
- When the check fails, its files stay pending, so each next edit of one of its sources runs it again on them all, until it passes. Then it counts from zero.
- At task end the check runs as usual, even before reaching `every` or `lines`, since every edit marks its project as changed. When it passes there, its pending files are forgotten too.
- `every` and `lines` must be whole numbers of 1 or more. Without both, or with `every: 1`, the check runs after each edit. They have no effect on a `task-end` check.
- The pending files are kept in your user's state directory (`%LOCALAPPDATA%\interlint\pending` on Windows, `$XDG_STATE_HOME/interlint/pending` or `~/.local/state/interlint/pending` elsewhere), never in the project. When they cannot be read or saved, the check runs after that edit.

## At task end

Every check runs, `edit` ones included. A project whose checks all pass is remembered as passing, with its files as they are.

```bash
interlint check --when task-end --changed
```

With `--changed`, only the checks of the projects that changed since their checks last passed run. The OpenCode plugin and the Claude Code `stop` hook use it, so the end of a task does not run the checks of a project nobody changed. A project is a check's `dir`, or the directory of `interlint.yaml` for a check without one. It counts as changed when:

- an edit check call (`--when edit`, which the agent integrations run after every edit) named one of its files, whatever the file is; or
- a file was added, changed or removed since its checks last passed, by any means, such as a shell command. Build output (`target/`), `node_modules/` and hidden directories such as `.git/` do not count. A commit does not count either: it leaves the files as they are.

With `--file <path>`, which can be repeated, only the projects that hold one of those files run. The agent integrations pass the files a subagent changed, so it gets the failures of its own projects only:

```bash
interlint check --when task-end --changed --file orders/src/main/java/shop/Order.java
```

A project Interlint has not seen before counts as unchanged until something above happens, so the first task end does not run every project. A project whose checks fail stays changed, so they run again at the next task end, and so does a project changed while its checks ran, by an edit or any other means: a project is remembered with its files as the checks saw them. A check that writes files outside `target/` therefore makes its project run once more at the next task end. The state is kept in your user's state directory (`%LOCALAPPDATA%\interlint\projects` on Windows, `$XDG_STATE_HOME/interlint/projects` or `~/.local/state/interlint/projects` elsewhere), never in the project.

### Reports from the agent's own build

With `--changed`, a check does not run when a build since the project's last change already left its reports, such as `mvn clean verify` run by the agent because your `AGENTS.md` asks it to. The check passes, and the project is remembered as passing, when all of these hold:

- Each report the check's command writes is in `target/`, written after the last change to the project's files. Removing a file counts as a change too.
  - `report: archunit`: the Surefire report of every class that `-Dtest` names, as `init` writes it. A command without `-Dtest`, or with a pattern or a method in it, always runs.
  - `report: maven`: the report of each `checkstyle:check`, `pmd:check` or `spotbugs:check` goal of the command, in every module where it is. A command without one of those goals always runs.
  - `report: jacoco`: JaCoCo writes its result to no report, so Interlint checks again instead. When every module with tests (`src/test/java`) has a `target/jacoco.exec`, each written after the last change, and that module's Surefire reports (`target/surefire-reports/TEST-*.xml`) were all written after it too and list no failed test, it runs the command without its lifecycle phases, as in `./mvnw jacoco:check@check -fae -Djacoco.append=false`: its `jacoco:check` goals read that data and no test runs, and its profiles and properties still apply. The check passes when they do. Otherwise, or when they fail, the check runs as usual: a build with `-DskipTests` or `-Djacoco.skip`, or one that stopped before `test`, leaves no new data, and a build with a failing test or that ran only some tests fails the Surefire condition. A command without a `jacoco:check` goal always runs. A build without `clean` adds its coverage to the data already in `jacoco.exec`, so tests deleted since an earlier build would still count: ask the agent for `mvn clean install` or `mvn clean verify`.
- The reports were written whole, not cut short by a build that stopped, and list no failure. A Checkstyle, PMD or SpotBugs report must list no finding at all: without Maven's exit code, Interlint cannot tell what the build accepted.

Otherwise the check runs as usual. So a build that skipped the tests or a plugin, or ran only some tests, does not count. A file changed while that build ran, after the build read it, still makes the reports look new: keep the agent's build as the last thing that touches the files.

Without `--changed`, as when you run `interlint check` yourself, and after an edit, every check runs.

## Protected files

An agent can pass a check by weakening its rule: editing the ArchUnit test, `checkstyle.xml` or the ESLint configuration. Interlint cannot tell whether a change like that is what the task needs, so it asks you.

```yaml
protected:
  - "src/test/java/**/ArchitectureRulesTest.java"
  - config/checkstyle.xml
  - eslint.config.js
```

- Each entry is a path or a glob relative to `interlint.yaml`, inside the project. `**` matches any number of directories, `*` any characters within one, and `?` one character. Case does not matter. Globs do not look inside `node_modules`, `.git` or `target`.
- `interlint.yaml` is always protected, even without `protected:`.
- **Before an edit,** the agent asks you whether it may change a protected file, with a message that names it. Claude Code and GitHub Copilot ask through Interlint's `pre-edit` hook, and the OpenCode TUI through the plugin. Codex cannot ask, and OpenCode Desktop grants the question without showing it. In Codex and OpenCode the agent is told right after the edit that it changed a protected file, and the edit never counts as approved, even one you allowed in the OpenCode TUI: the plugin cannot tell your answer from Desktop's.
- **When the session starts,** the agent hooks keep a hash of each protected file. A resumed or compacted session keeps the first one.
- **At task end,** a protected file that differs from that hash, or was deleted, blocks the main agent's task end. The message names each file and asks the agent to put it back as it was. A change you approved in the agent's prompt does not count: it becomes the new reference. A change made any other way, such as from the terminal, does. A file created since the session started that matches a glob does not block.
- The block counts towards the same limit of 3 as the checks: after 3 blocks in a row, the task may end and you see the files. A new session starts from the files as they are then.
- A subagent's stop does not check protected files: its main agent's task end does.
- Each blocked task end is kept in your [metrics](#metrics) as a check named `protected files`, with `report: protected` and one violation per file, `protected file changed` or `protected file deleted`. An older Interlint skips these lines.

`interlint check` run by hand checks no protected file: it has no agent session. Hooks set up by an older `interlint init` keep no hash, so nothing is protected until you run `init --agent <agent>` again.

This is not a sandbox: the agent can still change files on disk, Interlint's state included. It makes weakening a rule visible: the agent is blocked, you are told, and the metrics keep it.

## Multi-module projects and workspaces

Start Interlint, and your agent, in the root of either layout:

- **A Maven reactor**: a `pom.xml` with `<modules>`. `init` looks for `@ArchTest` classes in `src/test/java` of every module, and for Checkstyle, PMD and SpotBugs in the build of every module.
  - A plugin the parent only declares in `<pluginManagement>` counts when a module turns it on in `<build><plugins>`; one no module turns on is left out. The checks name the executions the parent manages, as in `checkstyle:check@style`.
  - The `architecture` check builds only the modules with the `@ArchTest` classes and the modules they depend on (`-pl launcher -am`), and tells Surefire not to fail in the modules without them (`-Dsurefire.failIfNoSpecifiedTests=false`).
  - `report: archunit` and `report: maven` read the reports of every module and show each source path from the root, such as `infrastructure/src/main/java/com/acme/Order.java:12`.
- **A workspace**: a directory without `pom.xml` that holds several Maven projects, each a single project or a reactor with its own Maven Wrapper, for example as Git submodules. Other projects, such as a Node front end, are ignored. `init` writes the checks of every Maven project it finds up to three levels down, each with its `dir`, and names them after it:

```yaml
# Generated by interlint init.
checks:
  - name: orders/architecture
    dir: orders
    run: ./mvnw -q test -pl launcher -am -Dtest=OrdersArchitectureTest -Dsurefire.failIfNoSpecifiedTests=false -Dcheckstyle.skip -Dpmd.skip
    report: archunit
    when: edit
    every: 5
    lines: 100
  - name: orders/checkstyle
    dir: orders
    run: ./mvnw -q checkstyle:check@style
    report: maven
    when: edit
  - name: billing/checkstyle
    dir: billing
    run: ./mvnw -q checkstyle:check@style
    report: maven
    when: edit
```

- `dir` is the directory the check runs in, relative to `interlint.yaml`, so each check uses its own project's `pom.xml`, Maven Wrapper and configuration. Without `dir`, a check runs where `interlint.yaml` is. A `dir` outside that directory is an error. A check whose `dir` does not exist, a typo or a removed Git submodule, fails at every task end with `✗ <check> · its dir "<dir>" does not exist`, changed or not, so the agent and you always see it; the other projects still run. After an edit it is left to task end, so it does not block every edit.
- Violations show their path from the workspace root, such as `orders/infrastructure/src/main/java/com/acme/Order.java:12`.
- A workspace can mix Maven projects and npm projects with [ESLint](#eslint) or [dependency-cruiser](#dependency-cruiser): `init` writes the checks of each, such as `web/eslint` with `dir: web`. It looks for an npm project in the root and up to three levels below it, never inside a Maven project or in `node_modules`, `dist`, `build` or `coverage`.
- After an edit, only the `edit` checks of the project that holds the file run. A file outside every project runs nothing.
- At the agent's task end, only the projects it changed run (see [At task end](#at-task-end)).

## Metrics

Every `interlint check`, and every check a hook or the OpenCode plugin runs, keeps one line per check in your user's state directory, never in the project:

- Windows: `%LOCALAPPDATA%\interlint\metrics\<project key>\<YYYY-MM>.jsonl`
- elsewhere: `$XDG_STATE_HOME/interlint/metrics/<project key>/<YYYY-MM>.jsonl`, or `~/.local/state/interlint/metrics/...`

The project key is a short hash of the project's directory. There is one file per project and per month (UTC). Interlint only adds lines and never removes a file: delete old months yourself if you want.

Each line is a JSON object:

```json
{"v":1,"at":"2026-11-05T10:20:30.000Z","interlint":"1.9.0","projectKey":"3f2a9c1d0b7e4a65","project":"shop","when":"edit","check":"pmd","report":"maven","result":"violations","durationMs":2140,"violations":[{"rule":"EmptyCatchBlock","type":"pmd","file":"src/main/java/shop/Order.java"}],"agent":"claude-code","session":"9bab2274-…","model":"claude-opus-5-5"}
```

- `v` is the version of the line format. `project` is the folder name of the project, not its path.
- `when` is `edit` or `task-end`. `report` is the check's `report`.
- `result` is `passed`, `violations`, `failed` (the command failed without a report that explains it), `missing-dir`, `broken-build` or `skipped`. A skipped check has `skipped`: `pending` (it waits for more edits, see [Every N files or lines](#every-n-files-or-lines)), `unchanged` (its project did not change since its checks passed, with `--changed`) or `build` (it passed on the reports of the agent's own build).
- `violations` has, for each violation, its rule, its type (`architecture`, `checkstyle`, `pmd`, `spotbugs`, `coverage` or `eslint`; dependency-cruiser's are `architecture`, as ArchUnit's) and its file from the directory of `interlint.yaml`. At edit, it has only what the agent was shown. No line number, message or code is kept.
- `agent`, `session` and `model` say who ran the check, and `subagent: true` with `agentType` when a subagent did. OpenCode also gives `provider`. A field the agent does not give is left out. A check run by hand has none of them.

The lines are plain text: you can read them with any tool, and they never leave your machine. Interlint has no telemetry, no account and no server, and makes no network calls: `interlint metrics` and `interlint metrics report` read these files on your machine, and the HTML and PDF reports load nothing from the internet. When a line cannot be written, as on a full disk, it is lost and the checks give the same result and output.

To keep no metrics, add this to `interlint.yaml`:

```yaml
metrics: false
```

### `interlint metrics`

```bash
interlint metrics
```

Sums up the metrics of the project in the current directory, or in `--cwd <dir>`, in a few lines:

```text
Interlint metrics · shop · 2026-11-05 to 2026-11-06

Checks run: 4 (1 skipped) · violations: 24
By type: checkstyle 21 · pmd 2 · architecture 1
Top rules:
  6  checkstyle  LineLength
  5  checkstyle  MissingJavadocMethod
  4  checkstyle  EmptyCatchBlock
  3  checkstyle  MagicNumber
  2  checkstyle  FinalClass

By model (violations per check run):
  claude-opus-5-5   7.33  (3 checks, 1 session)
  unknown           2.00  (1 check, 0 sessions)
By agent (violations per check run):
  claude-code   7.33  (3 checks, 1 session)
  manual        2.00  (1 check, 0 sessions)

Sessions: 1, 3.0 checks run on average, 3 at most
Task-end blocks: 1, 1 fixed later in the session
Time spent on checks: 20.0s
```

- **Checks run** leaves out skipped checks, shown in brackets.
- **Violations** count once in every run that shows them: a violation the agent leaves unfixed through three edits counts three times. It is how often the agent was told about it.
- **By model** and **by agent** compare violations per check run, not totals, because a model used more has more violations. Each line says how many checks and sessions are behind it. `unknown` is a check whose agent did not give the model; `manual` is a check run by hand.
- A **task-end block** is a task end in an agent's session where a check did not pass. It is fixed when a later task end of the same session passes. When Claude Code already let the task end after 3 blocks, a fourth failure still counts as a block.

Options, for both `interlint metrics` and `interlint metrics report`:

| Option | What it does |
|---|---|
| `--all` | Every project of the user, not only the current one |
| `--since <YYYY-MM-DD>` | Only the events from that day on, in UTC |
| `--agent claude-code\|codex\|copilot\|opencode` | Only the events of that agent |
| `--cwd <dir>` | The project to read, instead of the current directory |

Without metrics, it says so and where they are kept, and exits with 0. A line of a metrics file that is not an event, such as one edited by hand, is skipped, and the output says how many were.

### `interlint metrics report`

```bash
interlint metrics report
```

Writes the full report in Markdown to `interlint-metrics.md` in the project, ready to keep, share or paste into a pull request. It has the totals, violations by type, the top 20 rules, tables by model and by agent, a table of sessions, task-end blocks and their fix rate by model, the time spent on each check at edit and at task end, and the checks and violations week by week.

It also has charts:

- bars of the violations by type, and of the top 10 rules;
- a pie of the failed checks by model, each slice with the checks and sessions behind it, beside bars of the violations per check run by model. The pie shows absolute shares: a model used more has a larger slice, so compare models by the bars;
- bars of the time spent on each check, at edit and at task end;
- the checks run and violations week by week.

A chart with nothing to draw is left out. In Markdown the charts are [Mermaid](https://mermaid.js.org/) blocks: GitHub and GitLab draw them; other viewers, such as the VS Code preview without an extension, show their text.

`--format` picks the file:

| Format | File | What it is |
|---|---|---|
| `md` (default) | `interlint-metrics.md` | Markdown with Mermaid charts |
| `html` | `interlint-metrics.html` | One self-contained page with the charts drawn in SVG. It opens in any browser, offline, and prints well |
| `pdf` | `interlint-metrics.pdf` | The HTML page printed to PDF, ready to send |

```bash
interlint metrics report --format pdf
```

To write the PDF, Interlint runs an installed Chrome, Edge or Chromium, headless, in a profile of its own; an open browser window is not touched. It looks for them where they are installed on Windows and macOS, and on the `PATH` on Linux (`google-chrome`, `chromium`, `microsoft-edge` and their variants). Without one it writes nothing, exits with 2 and says so:

```text
interlint: could not write a PDF: no Chrome, Edge or Chromium was found. Use --format html and print it to PDF from a browser.
```

- `--out <path>` writes it elsewhere, from the current directory.
- It never replaces an existing file: it exits with 2 unless you pass `--force`.
- Without metrics, it writes nothing, in every format.
