adhere

A linter for rules a normal linter cannot check, such as "Business logic should live in services", or "modules should expose lots of functionality behind a small API". Define rules as formatted markdown:

---
description: A third party API going offline should not also take our app down.
---

Our APIs should never be coupled to some third party API on a critical path. The user facing
side should be unaffected if it goes offline, and ingestion should happen in a separate asynchronous process.

## Should

```ts
import googleMaps from "./lib/maps"
import db from "./lib/db"
import redis from "redis"
import cron from "node-cron"

// asume this is called by /api/restaurants/:zipcode
export async function findRestaurants(zipCode: number) {
  const results = db.restaurants.find({ where: { zipCode }})
  return results
}

export async startWorker() {
  cron("0 0 * * *", async () => {
    const since = Number(await redis.get("maps:sync:timestamp"))
    const items = await googlemaps.findAll({ since, limit: 100 })
    const syncItem = item => db.restaurants.upsert(item)
    const next = items.sort((a, b) => b.id < a.id).at(-1)?.timestamp
    const touch = () => redis.set("maps:sync:timestamp", next ?? Date.now())

    return Promise.all(items.map(item => syncItem(item))).then(touch)
  })
}
```

## Never

```ts
import googleMaps from "./lib/maps";
import db from "./lib/db";

// asume this is called by /api/restaurants/:zipcode
export async function findRestaurants(zipCode: number) {
  // what happens when google maps goes down? how about latency? how about costs?
  const results = await googleMaps.findAll({ where: { zipCode }, limit: 100 });
  return results;
}
```

Your rules are parsed, then adhere asks Jev (TypeSafe AI's System One model) whether the file breaks each rule, gets a calibrated probability per rule, and reports the ones above a threshold with the section of the file Jev points at. The report uses the same frame as vp lint.

Here's a demo of what the output looks like.

Demo 🎬

Presets for TypeScript, React, security, Effect, and alchemy are included. Run them to quickly adhere your agent to recommended rules.

bun add -g @drkmttr/adhere
adhere login # save your typesafe api key
adhere lint --preset typescript,react

Rules a normal linter can check exactly, such as a banned import or a type error, belong in that linter. While it lints, adhere asks Jev whether a normal linter could check each of your rules. adhere validate lists the ones it thinks belong in a regular linter, and detects contradictions between your rules.

• Install
• Quick start
• Generate rules from your repo
• Install rules from other repos
• Check for contradictions
• Live evals
• Writing good rules
• Commands
• Reading the report
• Rule format
• Config
• Other Providers
• Running lint
• Comments and suppressions
• Cache
• Agent skills
• How a file is judged
• Upgrading
• Development
• License

Add adhere to your repo's dev dependencies, and run it with npx adhere or bunx adhere:

npm install -D @drkmttr/adhere

Or download the standalone executable, which needs no Node or Bun:

curl -fsSL --create-dirs -o ~/.local/bin/adhere \
  https://github.com/darkmatter/adhere/releases/latest/download/adhere-$(uname -s)-$(uname -m)
chmod +x ~/.local/bin/adhere

• The npm package brings its own TypeScript compiler. Opt in with --type-aware or typeAware: true to add both symbols and references; type awareness is off by default. No other compiler setup is needed.
• The standalone executable has no compiler. It runs the default, compiler-free audit with workspace context, or code alone with reads: []. Type-aware audits require the npm package or a checkout with its development dependencies. It suits a global install that your agent config can always call.
• It is built for macOS and Linux, on arm64 and x64, and for Windows x64: download adhere-Windows-x86_64.exe from the latest release.
• adhere sends each file it judges, with what it reads beside it, to Jev at api.typesafe.ai, authenticated with a TypeSafe AI API key.

adhere login             # prompts for the key, masking what you type
adhere login < key.txt   # reads it from stdin instead
adhere logout            # deletes the saved key
adhere login --openai    # saves an OpenAI API key, for the openai provider
adhere logout --openai   # deletes it, and only it

• The key is saved to ~/.config/adhere/credentials.json, or under $XDG_CONFIG_HOME when that is set, readable only by you. An OpenAI key is saved beside the TypeSafe AI one, for a config whose provider is openai(); see Providers.
• TYPESAFE_API_KEY, when set, takes precedence over the saved key, so CI can pass a key without a login. OPENAI_API_KEY does the same for OpenAI's.
• The key is read only when a request is about to be sent. A run the cache answers in full needs no key and no network.

npx adhere init        # .adhere/config.ts, two example rules, and the dependency
npx adhere login       # save your TypeSafe AI API key, once
npx adhere validate    # check your rules' wording, and ask Jev whether any contradict
npx adhere lint        # audit the working directory
git add .adhere        # commit the rules, and the judgments they cost

adhere init creates a config file, some example rules, and adds adhere as a dev dependency.

It is safe to rerun: existing files are reported as skipped, and only --force overwrites them.

Let an agent write your first rules with you. The adhere-setup skill walks it through setting adhere up in your repo:

1. It reads where your conventions live: AGENTS.md, CONTRIBUTING.md, docs and ADRs, your lint config, recent review comments, and the code others copy from.
2. It drafts the conventions a normal linter cannot check as rules, each with real code from your repo, and sets aside the ones a linter could check.
3. It adds the presets that fit your stack, and rules from your organization's shared repo, if you have one.
4. It shows every candidate in one list, with its evidence, and imports the ones you choose.
5. It validates them, walks you through the first lint and what it costs, and adds adhere to CI.

It stops to ask you at each of those decisions, and never asks for your API key.

skills add darkmatter/adhere   # install adhere's skills for your agent

Then ask your agent to set adhere up.

An organization's rules can live in one repo's .adhere/rules/, and other repos copy them in with adhere install:

adhere list darkmatter/standards                        # each rule there, with its description
adhere install darkmatter/standards                     # every rule
adhere install darkmatter/standards/data                # the data topic
adhere install darkmatter/standards/data/brand-ports    # one rule
adhere install darkmatter/standards#v3                  # every rule, as tagged v3

• Copies land in this repo's .adhere/rules/org/repo/. So data/brand-ports from darkmatter/standards is .adhere/rules/darkmatter/standards/data/brand-ports/, the rule darkmatter/standards/data/brand-ports, and two repos' rules never collide.
• The copies are the repo's own rules from then on: commit them, edit them, or start new rules from them. Nothing tracks where they came from.
• A later install skips a rule already there, as init does. --force replaces its directory, edits and all.
• A rule's whole directory is copied. The source's config, its inline rules, and its cache are not.

Read what you install. A RULE.ts is copied with the helpers beside it, and runs whenever lint does, in CI too. adhere list names a RULE.ts without its description, since reading it would run it.

The source is cloned with git from https://github.com/org/repo.git, so a private repo needs git's credentials for GitHub, as gh auth setup-git sets up. To clone over SSH instead, let git rewrite the URL: git config --global url.git@github.com:.insteadOf https://github.com/.

adhere init --shared org/repo scaffolds a repo whose rules other repos copy in with adhere install, instead of one that lints itself. It writes the two example rules and no config, since install copies only rule files, and with them:

The repo is public unless you answer yes when init asks, at a terminal, whether to make it private. Other repos then need git's credentials for it to list and install its rules. Without a terminal it is public: change visibility in the stack to make it private.

Two rules contradict when no code can follow both, such as one that says errors must be thrown and one that says they must be returned. Each rule reads fine on its own, so a contradiction shows up only as code that breaks one rule or the other whatever you do. adhere validate finds them before lint does:

adhere validate                  # your rules
adhere validate --preset effect  # your rules beside a preset's

Found 1 contradiction among configured rules:

1. No code can follow both (0.91):
   - errors/throw-tagged-errors (/repo/.adhere/rules/errors/throw-tagged-errors/RULE.md)
     A function that fails must throw a tagged error, never return an error value.
   - errors/return-results (/repo/packages/api/.adhere/rules/errors/return-results/RULE.md)
     A function that fails must return a Result, never throw.

Resolve by editing one rule, narrowing a nested rule's scope, or using the same rule id when the nested rule is meant to shadow the root rule.

It asks Jev about each pair of rules that apply to the same files, so it needs the API key, as lint does. A contradiction fails it, with exit code 1, so it can gate a pull request that adds a rule, as the workflow adhere init --shared writes does.

It also runs two checks that are advice and never fail it:

• Wording: each rule worded otherwise than the rule writing tips recommend, with its file and how.
• The linter check: while lint judges a file against one of your rules, it also asks Jev whether a linter or type checker could decide the rule exactly, on 10 files per rule. A rule flagged on 7 or more of them probably belongs in a regular linter. One flagged on 3 to 6 reads differently from file to file, so its description should say more precisely what it applies to. Preset rules are left out.

Two rules with the same id are never compared: a nested rule that shares an id shadows the other on purpose.

Try a change to a rule on your own code before you rely on it: run the current rule and the changed one side by side, and compare what each flags.

1. Copy the rule's directory under a new id:

   cp -r .adhere/rules/data/brand-ports .adhere/rules/data/brand-ports-next

2. Give the copy level: warning in its front matter. Its findings show in amber and never fail the run, so the experiment can sit in the repo, and in CI, while you watch it.

3. Change the copy: its description, its examples, its appliesTo or excludeIf. To try giving Jev more to read, make the copy a RULE.ts with an appendState hook.

4. Run adhere lint, or adhere lint --filter '<glob>' to try it on part of the repo first, and compare the two rules' findings on the same files.

Judge the two by recall, the share of real violations each catches, and precision, the share of its flags that are real. Check the findings by hand, or with the adhere-fix skill, which verifies each one against its rule and the code. Then keep the better version under the original id, and delete the other.

• The copy costs nothing until you change it. Judgments are cached by the rule's text, not by its id, its level, or its threshold, so a copy that reads the same as the original answers from the original's cache. Each change after that judges the copy, and only the copy, once per file.
• Keeping the winner is free. Moving the winning text to the original id reuses its cached judgments.
• Counting each rule's findings takes a pipe: adhere lint --yes | grep -c 'data/brand-ports-next:'.

We've evaluated how Jev reads a rule, on the presets and on other repos, to catch the most violations with the fewest false positives. The eval has every study; these are the lessons for writing a rule.

• Say "must" and "never", in the description and in the headings over the code, or "should" and "should not" for a guideline. Rewording the presets' descriptions this way, with a bad example per rule, was the largest gain of any study: at 0.8, as many caught, and 1 wrong where there had been 5 or 6 (study).
• Give one example of each kind: one must block and one never block. A bad example helped every wording, and at 0.9 caught 24 violations with none wrong, where there had been 17 (study). Either kind alone did worse, and three of each did no better, for 1.58 times the tokens (study).

adhere validate lists each rule worded otherwise.

Bare adhere prints the help. adhere <command> --help lists a command's flags, and adhere --completions <shell> prints a completion script.

A finding looks like this:

  × data/brand-ports: A port must be a branded, range-checked integer, never a bare number.
    confidence 0.93 · context 0.88
   ╭─[src/server.ts:6:3]
 1 │ import { Effect } from "effect";
 2 │ import { listen } from "./listen.ts";
 3 │
 4 │ export const serve = Effect.gen(function* () {
 5 │   const host = process.env.HOST ?? "localhost";
 6 │   const port: number = Number(process.env.PORT ?? 3000);
   ·   ──────────────────────────────────────────────────────
 7 │   yield* listen({ host, port });
 8 │   yield* Effect.log(`Listening on ${host}:${port}`);
 9 │ });
   ╰────
  hint: const Port = Schema.Int.pipe(
          Schema.check(Schema.isBetween({ minimum: 1, maximum: 65535 })),
          Schema.brand("Port"),
        );

  confidence  0–0.74 < 0.8 < 0.85–1  Jev's probability that the file breaks the rule
  context     0–0.49 < 0.6 < 0.70–1  its probability that the file shows enough to decide

Found 1 error.
42 files, 3 judged, 39 cached.

Score colors. On a terminal, each score is colored by where it sits around its threshold:

• If you're near the threshold (orange), consider adjustments.
• Red is below the threshold, so lint never reports it: only the legend shows that range.

Low context. Jev sees the file and what adhere reads beside it, not your whole repo. So we also ask whether that shows enough to decide the rule at all. When context is below 0.6, it means Jev thinks it needs more info, which you can add with an @adhere comment. You may also see a hint:

  warning: this file may not show enough to check this rule
     help: add what the code relies on outside this file as a note Jev reads:
           // @adhere <the fact>, and how you know it

• On the eval, most findings with this warning were false, where about one in five of all findings was (study). Check what the code relies on outside the file before acting on it.
• If you feel the threshold is too low/high, override it using sufficiencyThreshold in the config.

A repo's own rules live in .adhere/rules/, organized just like skills:

.adhere/
  config.ts           optional
  cache/              commit it
  rules/
    data/             a topic: a directory that holds no rule
      brand-ports/
        RULE.md       the rule data/brand-ports
      columns/
        RULE.ts       a rule written in TypeScript
        schema.ts     a helper it imports, not read as a rule

• The directory's path is the rule id: .adhere/rules/data/brand-ports/RULE.md is data/brand-ports.
• A rule can be markdown RULE.md, or typescript RULE.ts. A directory with both refuses the run.
• Files not named RULE are ignored.

A RULE.md is front matter, then a body that holds the rule's code:

---
description: A port must be a branded, range-checked integer, never a bare number.
threshold: 0.8
---

Why: a bare `number` accepts 70000 and -1.

## Must

```ts
const Port = Schema.Int.pipe(
  Schema.check(Schema.isBetween({ minimum: 1, maximum: 65535 })),
  Schema.brand("Port"),
);
```

## Never

```ts
const port: number = Number(process.env.PORT);
```

• A rule needs code under at least one heading.
• A rule is a requirement ("must", "never") or a guideline ("should", "should not"), and cannot mix the two.
• A rule with only a never block suits a rule with no single correct form to show, such as a hand-rolled retry loop or an error caught and dropped.
• Neither goes in the other's place: code that must never be written, under must, reads to Jev as the pattern to follow.
• Prose around the code is the rule's details: Jev reads it after the description, so use it to say why the rule holds or where it does not apply. The report shows the description alone.

appliesTo and excludeIf say where a rule applies, apart from what it asks for. Each is a list of descriptions of code: a JSON array on one line in front matter, or an array in a config or a TypeScript rule.

---
description: Structured variants must be Schema.TaggedClass members of a Schema.Union, never hand-written object types joined by a tag field.
appliesTo: ["a declared union type or schema"]
excludeIf: ["a type that mirrors a third-party format whose tag key that format fixes, such as a Slack Block Kit block"]
---

The questions are about the code that breaks the rule, not the whole file, so a file with a real violation beside code an excludeIf describes keeps its finding.

A yes is a probability above 0.5. At --log-level debug, lint logs each finding its matchers dropped, with their scores.

Narrowing the description often works better. In the preset study, Jev scored an excludeIf near 0.5 for real and false findings alike. See Writing good rules.

By default, Jev reads the file's code and its imported workspace packages, with no native compiler startup. Opt in with typeAware: true in the config or adhere lint --type-aware to add both compiler context maps for every rule:

symbols omits standard-library and Node/Bun runtime built-ins, including their methods. Project and third-party symbols remain, even when they share a built-in name. Built-in type names can still appear inside those symbols' type signatures.

references is a flat string-to-string map. Keys keep the symbol's name as used in the target code, including import aliases, and the pathname's original casing. Values are complete declaration excerpts, not incoming reference call sites. Overlapping declarations under one key are merged; disjoint excerpts are joined with … between them. For example, code importing twice as scale can receive:

{
  "references": {
    "__comment": "Declarations of symbols used by the target code, provided only as context. Keys are symbol:repository-relative pathname; values are source excerpts, not incoming call sites.",
    "scale:src/Math.ts": "export function twice(value: number): number {\n  return value * 2;\n}"
  }
}

When sent to Jev, each enabled references, symbols, and workspacePackages map includes a reserved __comment explaining its contents. These comments are included before appendState hooks and restored after hooks. Top-level guidance also tells Jev that these maps are context only: judge the target code, not the additional declarations or metadata.

Each symbol's complete resolved content is truncated to 256 characters by default. Set maxSymbolLength in the config to change this limit. Documentation and JSDoc tags are first capped separately by maxSymbolDocumentationLength, also 256 by default; 0 omits documentation and tags. Smaller limits reduce request size but can cut off type signatures, overloads, useful details, or examples.

typeAware defaults to false. When enabled, it adds both symbols and references, regardless of reads. The reads setting now chooses workspace context only: its default is ["workspacePackages"]; [] omits that map. Legacy "symbols" or "references" entries in reads alone do not enable native context, and leaving them out does not disable it when typeAware is true.

// .adhere/config.ts
import { defineConfig } from "@drkmttr/adhere";

export default defineConfig({
  typeAware: true, // opt in to both symbols and references
  reads: [], // omit workspacePackages, not compiler context
});

For code alone, use reads: [] with type awareness off; do not pass --type-aware. To retain workspace context without a compiler, leave the settings at their defaults.

Each name is the key Jev reads it under, so a rule's description can name it in backticks, as the questions name code:

---
description: A function imported from one of this repository's own packages, which the file's `workspacePackages` names, must be called through the package's namespace, never imported by its own name.
---

## Must

```ts
import * as Orders from "orders-core";
```

## Never

```ts
import { parse } from "orders-core";
```

• symbols and references use the SDK and native compiler pinned to exactly 7.1.0-dev.20261009.1, which the npm package installs. This prerelease contains the tuple-reference serialization fix from microsoft/TypeScript#64080; SDK and native executable must match that exact version. They use each file's tsconfig.json, and work without one.
• symbols is still a name-to-string map. Distinct binding/narrowing types get distinct blocks; docs and JSDoc tags appear once per canonical symbol per file. It has no IDE labels or selected-call overload presentation. Symbol/type queries are batched, with independent SDK requests chunked to at most 8.
• A name adhere does not have refuses the run, so a misspelled one does not go unnoticed. So does reads in a rule: it is the config's alone.
• What adhere has no name for, such as a file of the repository's, a rule in TypeScript adds with appendState.

Cost and privacy. Opting into type awareness sends Jev more than the file it judges: whole declarations from other files, plus compiler-provided documentation and JSDoc tags in symbols, even with includeComments off. It also starts the native compiler during execution. The plan's estimate leaves those tokens out. Keep typeAware off to avoid that extra context and compiler work; changing reads only changes workspace context.

A rule's directory can hold it as a RULE.ts instead, which default-exports defineRule({...}), taking the fields a config's inline rule does. What TypeScript adds is appendState, a hook on what Jev reads for the rule:

// .adhere/rules/data/columns/RULE.ts
import { defineRule } from "@drkmttr/adhere";

export default defineRule({
  description:
    "A query must name only columns its table has in `schema`, and never a column it lacks.",
  must: 'db.select("id", "email").from("users")',
  never: 'db.select("mail").from("users")',
  appendState: async (state, file, Bun) => ({
    schema: await Bun.file("db/schema.sql").text(),
  }),
});

• The hook runs right before each request about the rule goes out. It gets the request's state, the file the request is about, and Bun's API, and what it returns is spread over the state.
• The description can name a key the hook adds, in backticks, as the questions name code.
• A RULE.ts is imported, as a config is, so its code runs on every lint.
• A rule with a hook goes to Jev in requests of its own, so only that rule reads what its hook adds. Each of those requests sends the file and its context again.
• What the hook reads outside the file is not part of the cache: when db/schema.sql changes, a file already judged is not judged again until it or the rule changes.

• Rules in the root .adhere/rules/ apply project-wide.
• A nested .adhere/ scopes its rules to the directory that contains it. A rule in packages/api/.adhere/rules/data/brand-ports/RULE.md has the same id, data/brand-ports, but applies only to files under packages/api/.
• If a nested rule has the same id as a root rule, the nearest containing .adhere/ shadows the less-specific rule for that subtree. Outside that subtree, the root rule still applies.
• Nested .adhere/ directories are not discovered under node_modules/, dist/, and the other skipped directories.

A repo that would rather keep its rules with the rest of its documentation can point rules at a directory such as docs/adhere/:

export default defineConfig({ presets: ["effect"], rules: "./docs/adhere" });

That directory holds its rules as .adhere/rules/ does, a directory per rule, and they apply project-wide.

A config file is optional. Without one, adhere reads the rules in .adhere/rules/ and any --preset. A config names presets, sets the model, the thresholds, and what Jev reads, or gives rules inline. It sits in the working directory of the repo being audited, at one of these paths (keep one):

• .adhere/config.ts, the default, next to the rules
• adhere.config.ts
• .adhere.config.ts

import { defineConfig } from "@drkmttr/adhere";

export default defineConfig({
  model: "jev-latest",
  threshold: 0.8,
  sufficiencyThreshold: 0.6,
  reads: ["workspacePackages"],
  typeAware: true, // optional; false by default
  presets: ["effect"],
  maxSymbolDocumentationLength: 256,
  maxSymbolLength: 256,
  exclude: ["**/generated/**"],
  overrides: { "effect/basics/instrument-with-pipe": "off" },
  rules: {
    "data/brand-meaningful-primitives": {
      description:
        "A primitive with semantic meaning, such as an id, email, URL, port, or count, must be a branded schema.",
      must: `
const UserId = Schema.String.pipe(Schema.brand("UserId"))
type UserId = typeof UserId.Type
`,
      never: "type UserId = string",
      threshold: 0.8,
    },
  },
});

• An invalid shape refuses the run.
• A config can import other files by relative path, but no packages besides @drkmttr/adhere: the executable does not resolve node_modules.

adhere asks TypeSafe's Jev by default. A provider asks another decision model instead, and adhere exports one for each model the providers study measured:

import { defineConfig, openai } from "@drkmttr/adhere";

// Asks with OPENAI_API_KEY, or the key `adhere login --openai` saved.
export default defineConfig({ provider: openai() });

• Without an apiKey, jev and openai ask with the key from Login.
• Each also takes fetch, what sends its requests.
• Clef cuts a request too long for it short rather than refuse it, so cloudflare skips a file whose request reaches clef's limit: 64,000 tokens, or 24,000 for clef-flash.

import { defineConfig, type Provider, RequestFailed } from "@drkmttr/adhere";

const mine: Provider = {
  model: "my-decision-model",
  ask: async (state, questions, { signal }) => {
    const response = await fetch("https://decisions.example.com/v1/decide", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ state, questions }),
      signal,
    });
    if (!response.ok) {
      throw new RequestFailed(`My model answered HTTP ${response.status}`, response.status);
    }
    return { answers: await response.json() };
  },
};

export default defineConfig({ provider: mine });

• Name presets in the config's presets, or on the command line with --preset, repeated or separated by commas, as in --preset effect,alchemy, in which case the config file is optional. Presets named in both places apply together.
• A topic, one of a preset's subdirectories, is a preset of its own: --preset effect/basics applies only the rules under presets/effect/basics/, and alchemy/secrets only alchemy's secrets rules. security has no topics.
• To change a preset's rule without copying it, use Overrides.

A config's overrides changes a rule by the id a report names it with, a preset's with the preset first, without copying its text into rules:

export default defineConfig({
  presets: ["effect", "alchemy"],
  overrides: {
    "alchemy/providers/idempotent-delete": { level: "warning", threshold: 0.9 },
    "effect/basics/instrument-with-pipe": "off",
  },
});

An id that no preset or project rule has refuses the run, so a typo does not go unnoticed. A rule of a preset the run does not name is accepted.

For the model and the threshold, highest first:

1. --threshold on the command line
2. the config file
3. presets, in order (a later preset wins)
4. the defaults, jev-latest and 0.8

For one rule:

• A rule's own threshold beats all of the above for that rule.
• An entry in overrides beats the rule's own threshold and level.
• A rule in rules replaces a preset rule with the same id.

--sufficiency-threshold beats the config's sufficiencyThreshold, which beats the default, 0.6.

• adhere lint reads the TypeScript files under the working directory: .ts, .tsx, .mts, and .cts. It does not read declaration files such as .d.ts, adhere's own config files, or JavaScript.

• When the working directory contains agents/, apps/, or packages/, only those trees are read.

• Below the working directory, anything under node_modules/, dist/, coverage/, vendor/, e2e/, references/, .adhere/, .agents/, .claude/, .direnv/, .alchemy/, or .vite/ is skipped. The directories above the working directory do not count.

• .gitignore is not consulted.

• A config's exclude lists globs, relative to the working directory, of files no rule judges, such as generated code. It leaves them out of every run, as --filter '!<glob>' leaves them out of one:

  export default defineConfig({ exclude: ["**/generated/**"] });

Tests are judged only by rules about tests, whose front matter says tests (see Rules as Markdown files). A test is:

• a .test or .spec file, such as a.test.ts or Button.spec.tsx;
• a fixture or test helper named as one, such as fixtures.ts, GitHubHttpFixtures.ts, ledger-copy.fixture.ts, linear-test-helpers.ts, or test-utils.ts;
• any file under a test/, tests/, __tests__/, testing/, fixtures/, fixture/, __fixtures__/, or __mocks__/ directory.

Before it judges anything, lint says on stderr what it found and what judging takes, and asks:

200 files and 14 rules: 2800 checks, 1400 cached.
Judging 100 files takes an estimated 100 requests to Jev, plus 1 or more for each file with a finding.
Those carry about 1.9 million input tokens: about $0.08 at $0.042 per million, and more for locating findings.
Estimates cover only code and workspace-package context; symbol/reference input, possible extra request splits, and size-skips are determined at send time.
? Estimates cover only code and workspace-package context; symbol/reference input, possible extra request splits, and size-skips are determined at send time. Send an estimated 100 requests to Jev, about $0.08? › (Y/n)

• It asks only with a terminal on stdin and stdout, and only when there is something to send. --yes sends without asking.
• The cost is adhere's estimate of the input tokens times the model's price. Jev charges only for input tokens: $0.042 a million for jev-latest, per TypeSafe AI's models page in September 2026. When type awareness is enabled, the estimate leaves out symbols and references, which adhere reads as it sends each file, so a run can cost more than it says.
• A run that stops loses nothing: files finished before it stopped are cached, so running again continues from there.

Three flags bound what a run does:

adhere lint --filter 'packages/api/**' --filter '!**/generated/**' --limit 100 --rpm 30

--limit counts files, not requests: one file can take several.

stdout still carries only the report, so the log can go to a file of its own:

adhere lint --log-level debug 2> adhere.log

Jev reads a file's code, not its comments. adhere takes every comment out before it hashes or sends a file, or a declaration from references, blanking it so every line keeps its number. The report's excerpts still show them. Compiler-provided documentation and JSDoc tags still reach Jev in the type/docs strings symbols sends when type awareness is enabled; these are not editor hovers.

Jev takes what comments claim at their word, which hid real violations in the studies: see Writing good rules.

A comment that says @adhere anywhere in it is a note for Jev, and stays. Write one for a fact the code relies on that the file cannot show, once you have checked it, with how you know:

/**
 * Deletes the activity. @adhere DeleteActivity succeeds on a missing
 * activity, so no not-found error needs catching; probed 2026-09-25.
 */

• A note informs Jev. It suppresses nothing, and Jev still judges the code around it.
• includeComments: true in the config sends every comment, for a project whose rules are about comments, such as doc comments on exports.

A finding Jev got wrong is suppressed in the code, with a comment saying why:

// adhere-ignore alchemy/providers/idempotent-delete -- DeleteActivity succeeds on a missing activity; probed 2026-09-25
delete: Effect.fn(function* ({ output }) {
  yield* sfn.deleteActivity({ activityArn: output.activityArn });
}),

• A comment names rules as a report does, separated by commas.
• What follows -- is the reason, for whoever reads the code next.
• A finding without lines is covered when its section overlaps the statement.
• Jev never reads these comments, even with includeComments: true.
• The summary counts the findings they suppress.

Judgments are cached in .adhere/cache/. Commit it. Every judgment is a paid request, and Jev's answers vary a little from run to run, so a committed cache gives everyone and CI the same findings without paying for them again, and a pull request changes the judgments of only the files it changes.

To keep the cache out of diffs, mark it as generated in .gitattributes:

.adhere/cache/** linguist-generated -diff

Where lint gates a merge. Anyone who can commit can also write a cache file saying that code passes. Lint a pull request against the cache as merged, not as the pull request has it. Only the files it changes are judged again:

rm -rf .adhere/cache && git checkout origin/main -- .adhere/cache
adhere lint --yes

Three skills teach an agent to work with adhere:

Install them with the skills CLI: skills add darkmatter/adhere. The binary carries all three, so adhere skill fix > .agents/skills/adhere-fix/SKILL.md works without a checkout.

Pipe the fix skill into an agent that runs without asking. The skill tells it that invoking the skill permits every adhere lint run and its cost, and adhere skill fix prints the skill of the adhere that runs, so its flags match:

adhere skill fix | codex exec --yolo
adhere skill fix | claude -p --dangerously-skip-permissions

Both turn off the agent's own permission checks, which suits a runner thrown away after the job. To keep Codex in its sandbox, let the sandbox reach api.typesafe.ai:

adhere skill fix | codex exec --sandbox workspace-write \
  -c sandbox_workspace_write.network_access=true -c approval_policy=never

• Set TYPESAFE_API_KEY from a secret.
• The agent adds no adhere-ignore comments or @adhere notes unless ADHERE_ALLOW_SUPPRESSIONS=1 is set in its environment, as in adhere skill fix | ADHERE_ALLOW_SUPPRESSIONS=1 codex exec --yolo. It then suppresses a finding it shows is false, or that three fixes did not clear, with the evidence in the comment. Without it, the agent leaves those findings, and its report ends by naming them and the variable.
• End the job with adhere lint --yes. The agent exits 0 whatever it left, so this step passes or fails the job. It judges only the files the agent changed, and reads the rest from the cache.

Do not run it on pull requests from forks. The agent reads their code with your secrets in reach and the network open, so code written to steer it can send them out.

1. Split. adhere splits the file into sections of whole statements, in runs of at most 30 lines.
2. Judge. One request per file asks Jev, for each rule, how likely the file is to break it.
3. Locate. A second request, only for rules above their threshold, asks which section and lines break the rule, and whether Jev sees enough to decide.

A file too long for Jev's context is skipped and counted in the summary.

Names and layouts from older versions:

Configs that previously enabled compiler context with reads: ["symbols", "references"] must now opt in with typeAware: true, or use adhere lint --type-aware. That switch enables both maps; reads only controls workspace context.

From a checkout, with Bun:

bun install
bun link          # puts `adhere` on PATH
adhere lint --preset effect

• In a checkout no platform package is installed, so bin/adhere.js runs src/main.ts with Bun instead. Type-aware audits use the checkout's own TypeScript; the default audit does not start it.
• bun run typecheck runs tsc and the linter.
• bun run test runs the tests.
• bun scripts/verify-npm.ts, after bun run build:npm, installs the built packages in a scratch project and explicitly enables typeAware: true to check symbols and references. It needs Node 24 or later, and sends Jev nothing.

Each platform's executable is its own npm package, @drkmttr/adhere-<platform>-<arch>, limited by os and cpu, and an optional dependency of @drkmttr/adhere, so an install fetches only its own machine's. Each depends on TypeScript's native compiler for its platform, @typescript/typescript-<platform>-<arch>, pinned to exactly 7.1.0-dev.20261009.1 to match the SDK. The package's bin/adhere.js finds both, and runs the executable with Node. The same executables are attached to each GitHub release, named for uname -s and uname -m as in adhere-Linux-x86_64, with LICENSE and THIRD_PARTY_NOTICES.txt, which go with any copy you redistribute.

adhere --version tells the builds apart:

Releases are cut by CI from pushed version tags. From a clean, up-to-date main, push the release tag:

git tag v0.3.0
git push origin v0.3.0

1. The tag push starts .github/workflows/release.yaml, which checks out main, derives 0.3.0 from v0.3.0, and runs bun run release -- --ci 0.3.0.
2. Release-it bumps package.json, commits chore: release v0.3.0 back to main, skips npm publish, and creates the GitHub Release for the existing tag.
3. release.yaml then calls the reusable publish workflow, .github/workflows/publish.yaml, directly, avoiding a chained GitHub Release event created by GITHUB_TOKEN.
4. The publish workflow verifies that package.json matches the release tag, builds the platform packages, attaches their executables to the GitHub Release, and publishes each package before @drkmttr/adhere, which it first lists them in as optionalDependencies at the same version.

CI, and the publish workflow before it publishes, run scripts/verify-npm.ts on Linux and on both Macs. Windows is built, but not run.

MIT. See LICENSE.