Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ingrain

Problem: your coding agent keeps breaking what your team already settled. It re-adds the dependency you removed, brings back the pattern you banned, and repeats the mistake you corrected last week.

Solution: ingrain keeps those rules in your repo, puts the relevant ones in front of the agent right before it edits a file, and blocks edits, commits and PRs that break them.

Rules come from two places:

  • Decisions you record (or that ingrain decisions extract proposes from your AGENTS.md, PRs, reviews, commits and sessions): “billing calls the payments client, never raw fetch”, with a reason, a scope and optional checks. They live in decisions/.
  • Lint rules learned from your corrections: when you keep fixing the same thing in agent code, ingrain rules mine and ingrain rules propose turn it into an ast-grep rule, tested on your history. They live in .corrections/rules/.

Nothing becomes a rule without a person accepting it.

Where to go next

Install

brew install wispagents/tap/ingrain   # macOS and Linux
# or from source, any OS:
cargo install --locked --git https://github.com/WispAgents/ingrain --tag v0.4.0 ingrain
# on Linux without the GUI libraries, or Rust older than 1.99: add --no-default-features

ingrain viewer, the desktop window, is in the macOS and Windows binaries. The Linux prebuilt binaries leave the viewer out, so ingrain runs in any container or CI image with nothing extra installed. For the viewer on a Linux desktop, build from source (Rust 1.99 or newer, plus libxkbcommon-dev and libwayland-dev): cargo install --locked --git https://github.com/WispAgents/ingrain ingrain. Building from source with the viewer needs Rust 1.99; --no-default-features builds without it on Rust 1.90.

Prebuilt binaries for macOS, Linux and Windows (x64 and arm64) are on the releases page. On Windows, unzip ingrain.exe into a folder on your PATH. Claude Code runs hooks through Git Bash there, and Git for Windows runs the pre-commit hook, so both work as on macOS and Linux.

Needs git. Optional: gh (logged in) to read GitHub PRs, reviews and issues; Claude Code (claude) or ANTHROPIC_API_KEY for extraction and for rules templates can’t express.

Quick start

cd your-repo
ingrain init      # decisions/, .corrections/, Claude Code hooks, git pre-commit hook

ingrain decisions add "Billing code calls the payments client, never raw fetch." \
  --reason "the client adds idempotency keys" \
  --scope "src/billing/**" \
  --forbid-pattern 'TypeScript:fetch($$$A)'

ingrain decisions extract --doc AGENTS.md   # propose decisions from your rules doc, PRs, commits, sessions
ingrain decisions review                    # accept / edit / reject

ingrain rules mine --pr-refs --github       # capture corrections of agent code
ingrain rules propose --explain             # learn and backtest lint rules from them
ingrain rules review                        # accept / edit / reject

git commit decisions/ .corrections/ -m "ingrain rules"

Just for you, with nothing committed: ingrain init --local, or ingrain init --global for decisions that follow you into every repo. See local and global stores.

Next: what the agent sees once ingrain is set up, and where checks run.

Use it from your coding agent

With ingrain installed, give your agent the ingrain skills, then ask it to “set up ingrain in this repo”. The ingrain-setup skill runs ingrain init (and installs the binary first if it’s missing, after asking), turns the rules in your AGENTS.md / CONTRIBUTING.md into decisions for you to approve, and commits on a branch.

Claude Code (plugin: skills + hooks):

/plugin marketplace add WispAgents/ingrain
/plugin install ingrain@ingrain

Any agent (Claude Code, Codex, Cursor, Copilot, Gemini CLI, opencode and more):

npx skills add WispAgents/ingrain
SkillUse it for
ingrain-setupInstall and set up ingrain in a repo, seed decisions from your docs
ingrain-decide“From now on we don’t use X”: record, change or look up a decision
ingrain-rulesLearn rules from past corrections, review them, set shadow / warn / block

Ask for “use ingrain just for me” to get ingrain init --local (nothing committed). Ask to “always” follow a rule in every repo to get a --global decision (local and global stores).

The plugin’s hooks act only in repos set up with ingrain init (or that see your global decisions), and step aside where the repo’s own .claude/settings.json already runs ingrain (no double checks). Without the ingrain binary they do nothing. Agents without hooks get an ingrain section in AGENTS.md (ingrain init --agents-md) and are caught by pre-commit and CI.

Decisions or learned rules?

DecisionLearned rule
Comes fromSomeone saying what code must do, recorded or extractedA mistake people kept fixing in agent code, mined from history
HoldsA sentence, a reason, a scope, optional checksAn ast-grep pattern, backtested on past corrections
CoversAnything: architecture, conventions, dependencies, scopeOnly code patterns a lint rule can match
EnforcedShown before edits in scope; with checks, a breaking edit is denied before it landsRuns after edits, in shadow → warn → block mode, promoted from its hit log
Changed withingrain decisions supersedeingrain rules mode, ingrain rules promote
Per-line overrideA comment naming the decision id (how)A comment naming the rule id (how)

Use a decision when you can say the rule up front, especially when it isn’t about code shape (“don’t add Redis”, “billing goes through the payments client”). Learned rules cover the rest: the mistakes nobody wrote down until they had fixed them a few times. Both are accepted by a person, can’t be edited by agents, and are checked together by ingrain check, the pre-commit hook and CI.

Decisions

One YAML file per decision, decisions/D-0001.yml, reviewed like code. See the decision file format for every field.

Record a decision

ingrain decisions add "Billing code calls the payments client, never raw fetch." \
  --reason "the client adds idempotency keys" \
  --scope "src/billing/**" \
  --forbid-pattern 'TypeScript:fetch($$$A)'

Agents run the same command with --propose; the proposal waits in decisions/pending/ until a person runs ingrain decisions review. To see what applies to a file before editing it: ingrain decisions for <path>.

Scope and changes

A glob scope matches the path; a bare directory means everything under it. A symbol matches files whose path names it or whose content mentions it. No scope, or **, is repo-wide.

To keep a decision for yourself instead of committing it, write it to a personal store: ingrain --local decisions add … (this repo, ids L-) or ingrain --global decisions add … (every repo, ids G-). See local and global stores.

To change one: ingrain decisions supersede D-0002 --decision "..." --reason "...", then ingrain decisions review. The old decision stays in force until a person accepts the new one.

ingrain decisions extract reads texts it hasn’t read before, oldest first, 400 per run: your --doc files (AGENTS.md, CONTRIBUTING.md), commit messages, GitHub PRs, reviews, issues and comments by the repo’s owners, members and collaborators, and what you typed in Claude Code sessions for this repo. A model returns proposals; near-duplicates of existing, pending or rejected decisions are dropped. Measured on public repos, 82% of extracted records were real, durable decisions (docs/ledger-study).

Learned rules

SourceSignal
Git fix-ups (ingrain rules mine)A human commit rewrites lines an agent commit added, within window_days
PR refs (--pr-refs)Same, on refs/pull/*/head, so fix-ups inside PRs survive squash merges
Review suggestions (--github)A ```suggestion comment on agent-written lines
Claude Code transcriptsThe agent edits, you reply, the agent rewrites what it just wrote

ingrain rules propose clusters corrections by what they removed, writes rules (templates first, then a model), and keeps a rule only if it catches the past mistakes, spares the fixed versions, and isn’t contradicted by agent code humans kept (the fix a rule came from never counts as its own evidence). One correction is enough to propose a rule, even with no other agent code to test on, so a first run has something to review. Each rule says whether it’s from a single fix or repeated fixes. Single-fix rules that look like one-offs are held back and listed with the reason: the code is still used 5+ times today, the name is generic (r3, data, .append(), or every fix was in test code; --all keeps them. Pass --min-corrections 3 (or set min_support in .corrections/config.yml) to wait for a mistake to repeat. Accepted rules start in shadow mode; ingrain rules promote moves them to warn and block from their hit log. Shadow hits are invisible to the agent, so leaving shadow needs hits a human later corrected (at least 3, and half of all hits, per the mined corrections); ingrain rules mode <id> warn moves one by hand. ingrain rules eval measures the whole loop on your history.

Accepted rules go to .corrections/rules/. Add --local or --global (ingrain --global rules propose) to keep them in a personal store instead; checks and hooks run the rules from every store.

Just for you: local and global stores

Decisions and learned rules don’t have to be committed. Next to the project’s decisions/ and .corrections/, ingrain has two personal stores. Nothing in them is written to the working tree:

StoreWhereApplies toDecision ids
project (default)decisions/, .corrections/the repository, shared with the teamD-0001
--local.git/ingrain/local/this repository, for you onlyL-0001
--global~/.config/ingrain/every repository on this machineG-0001

The global store is $INGRAIN_HOME when set, else $XDG_CONFIG_HOME/ingrain, else %APPDATA%\ingrain on Windows and ~/.config/ingrain elsewhere. Both variables must be absolute paths; relative ones are ignored.

Use ingrain in a repo without committing anything

ingrain init --local
ingrain decisions add "Use the fetch wrapper, not axios." --forbid-dep axios   # → L-0001

init --local creates .git/ingrain/local/, writes the Claude Code hooks to .claude/settings.local.json and adds that file to .git/info/exclude. It also installs the git pre-commit hook, which is local anyway. git status stays clean. All worktrees of the repository share the local store. --agents-md is refused, because AGENTS.md is committed.

In a repo set up this way, commands without a flag write to the local store. A later plain ingrain init still sets up the project store, if the team adopts ingrain.

Your own rules, everywhere

ingrain init --global
ingrain --global decisions add "Prefer early returns over nested ifs."   # → G-0001
ingrain --global rules propose                                            # learned rules go there too

init --global works outside a git repository. It creates the global store and adds hooks to your own Claude Code settings: ~/.claude/settings.json, or $CLAUDE_CONFIG_DIR/settings.json when that variable is set. Like the plugin’s hooks, these:

  • answer only in repositories set up for ingrain. Any global decision or rule counts, so they act in every repository once you have one.
  • step aside where the repository’s own .claude/settings.json or settings.local.json already runs ingrain, so nothing runs twice.

init --global doesn’t add the hooks when your settings file already enables the ingrain plugin. If you enabled the plugin somewhere else, pass --no-claude.

How the stores combine

  • Reads see everything. Hooks, ingrain check, decisions for, decisions list and decisions stale read the project, local and global stores together. If two stores have a rule with the same id, the first in project → local → global wins. rules accept refuses an id another store already has.
  • Writes go to one store. --local / --global go right after ingrain, before the command (ingrain --global decisions add …). Without a flag, ingrain writes to the project store when the repo has decisions/ or .corrections/. Otherwise it writes to the local store once init --local has run. Learned-rule commands (rules propose, review, accept, reject, mode, promote) use the flag the same way. rules mine stays per repository.
  • Ids pick the store. decisions supersede G-0001 puts the proposal in the global store. decisions accept, reject and show find the store from the id, so they need no flag. decisions review shows each proposal’s store.
  • Config. Each store has its own corrections/config.yml. A command uses the config of the store it writes to, which in a team repo is the project’s.

Checks and protection

  • Personal stores aren’t in git, so the pre-commit check reads them as they are. The project’s rules and decisions still come from the base revision. CI never sees personal stores.
  • A repository only gets the pre-commit hook from ingrain init or ingrain init --local run in it. Elsewhere, global decisions are enforced by the Claude Code hooks alone.
  • Agents can’t edit accepted files in a personal store: decisions/*.yml, corrections/rules/, corrections/config.yml and rejected.yml. They can’t accept, reject or retune them either, and can’t run init --local / init --global, without asking you. Proposals in pending/ stay free. There is no first-setup exception for personal stores: nothing ever commits them, so nobody would review what an agent accepted.
  • A repository that only sees your global decisions keeps its own decisions/ folder (ADRs, say) editable.
  • At session start, the agent is told that L- and G- ids are your personal decisions, and to record a decision with --global when you state a preference for every repository.

The viewer

ingrain viewer opens a desktop app on the repository you are in. It shows the same files the CLI reads: decisions/, .corrections/, your local and global stores, and the hit log.

Open it

ingrain viewer                    # the repository you are in
ingrain viewer ~/code/app         # another one
ingrain viewer --select D-0004    # straight to one decision
ingrain --global viewer           # only your personal rules
ingrain viewer --wait             # keep the terminal until the window closes

ingrain viewer returns at once; the window keeps running. Run it outside a repository to pick a recent one. You can also press ⌘O to pick a folder, or drop a folder on the window. Outside a repository, --global viewer shows your personal rules read-only: the CLI makes changes from inside a repository, so open the viewer from one to accept or reject them.

Review proposals

The Inbox shows proposals one at a time, decisions and rules together. A replacement shows the decision it retires, struck through, above the new one. A proposed rule shows the fix it learned from and its backtest.

KeyDoes
AAccept
RReject. Type why, then Return. Extraction won’t propose it again.
J / KNext / previous
EscCancel a reject

Extract decisions and Learn rules at the bottom of the sidebar run decisions extract and rules mine + rules propose. Their output shows while they run, and new proposals land in the inbox.

Read a decision

A decision’s page shows, top to bottom: the decision; why; what was not chosen; where it applies (click a path to see everything else that applies there); the check that enforces it, if any; its lineage (what it replaced and what replaced it); where it was decided (links open in your browser); and its git history. Click a commit to see what it changed.

The buttons at the top copy the line agents get, open the file, show it in its folder, or Supersede… it. Superseding writes a proposal. It replaces the decision once someone accepts it.

Rules

Set a rule’s mode with the Shadow / Warn / Block control. The page shows distinct hits, overrides, the last hit and hits per week for the last 12 weeks, from .git/ingrain/hits.jsonl.

Project, local and global

The viewer reads all three stores at once: the project’s (decisions/, .corrections/), yours for this repository (--local, L- ids) and yours for every repository (--global, G- ids). Personal items carry a local or global tag, and their page says where they are kept and who they reach instead of showing git history (they are never committed). Once you have any, the sidebar shows Stores with a count for each: click one to see only that store in every lens.

When and where

  • Timeline lists every decision by the month it was made. Replaced ones are hollow and struck through, with an arrow to the new one.
  • Applies to… takes a path (or a file dropped on the window) and lists the decisions scoped there, the ones that match a symbol in the file, the learned rules for its language, and the repo-wide ones. The decisions are the ones ingrain decisions for <path> gives agents.
  • Archive lists replaced decisions.

Keys

KeyDoes
⌘1 … ⌘6Inbox, Decisions, Learned rules, Timeline, Applies to, Archive
↑ ↓ or J KMove through the list
/ or ⌘FFilter
⌘OOpen a repository
⌘RReload
⇧⌘BShow or hide the sidebar

On Windows and Linux, ⌘ is Ctrl.

How it works

The viewer reads files with the same code as the CLI, on a background thread, and checks for changes every second. Every change it makes runs ingrain’s own commands, one at a time, so it does exactly what the commands do and nothing more. A file that doesn’t parse shows as a warning in the sidebar instead of disappearing. Sources open in your browser, or in their default app when they are documents or code inside the repository; nothing else opens.

It is part of the ingrain binary: on macOS and Windows, installing ingrain installs it.

On Linux, the prebuilt binaries leave the viewer out, so ingrain runs in any container or CI image with nothing extra installed. For the viewer on a Linux desktop, build from source (Rust 1.99 or newer, plus libxkbcommon-dev and libwayland-dev): cargo install --locked --git https://github.com/WispAgents/ingrain ingrain.

What the agent sees (Claude Code)

ingrain init adds one hook command per event to .claude/settings.json (ingrain hook <event>). Each is a no-op for teammates who don’t have ingrain installed, and all of them fail open.

HookWhat happens
SessionStartRepo-wide decisions go into the session, plus how to propose a new one
PreToolUse on Edit / Write / MultiEdit / NotebookEditThe edit is simulated first. If an added line breaks a decision’s check, the edit is denied with the decision and the way out. An edit that adds an ingrain-ignore / decisions-ignore comment asks the person first. Otherwise the decisions scoped to that file are shown, each once per session
PreToolUse on BashA command that could write accepted decisions, rules or .corrections/config.yml (sed -i, >, mv, rm, …), or that accepts, rejects or retunes them (ingrain rules mode, ingrain decisions accept, …), or git commit --no-verify, asks the person first
PostToolUse on Edit / Write / MultiEdit / NotebookEdit / BashLearned rules run on the edited file, or on the files the shell command changed (decisions too, since a command can’t be simulated). Warn: a note to the agent. Block: the agent must fix it, with the past human fix shown
StopRules and decisions are re-checked on the files this session edited. Something broken sends the turn back, up to stop_max_attempts times; after that the turn ends and the person is told

Agents can’t edit accepted decisions, rules or .corrections/config.yml (a broken config falls back to the defaults in hooks, so it can’t switch them off); they propose with ingrain decisions add --propose or ingrain decisions supersede, and a person accepts. The one exception is first setup: until a commit on any branch holds a decision, rule or ingrain config, the agent setting ingrain up may accept proposals and commit them, so “set up ingrain in this repo” finishes in a headless session too. People review that commit like any other; --no-verify is still asked.

The same protection covers the local and global stores, with no first-setup exception: they are never committed, so nobody would review an agent’s accept. ingrain init --local writes these hooks to .claude/settings.local.json, and ingrain init --global writes them to your own ~/.claude/settings.json, where they behave like the plugin’s.

Tested live with Claude Code 2.1.322: asked to write raw fetch in src/billing/, the write was denied before the file changed, and the agent explained the decision instead of working around it.

Where checks run

ingrain check runs learned rules and decision checks together, on added lines only, so existing code never blocks.

PathCommandOn a hit
Commitingrain check --staged (.git/hooks/pre-commit)the commit fails
Pull requestingrain check --diff base...HEAD --format github (action)annotations; failing check
By handingrain check [paths]listed; exit 1 if something blocks

Pre-commit and CI judge a change by the decisions, learned rules and config it started from, so a branch can’t retire a decision, delete a rule, set it to shadow or ignore its path, and break it in the same diff. CI also flags any change to decisions/ or .corrections/. Outside pull requests the Action compares with the default branch. The pre-commit hook goes where git runs hooks (core.hooksPath, or the main .git/hooks from a worktree).

To keep a line on purpose, add a comment with a reason, on the line or the line above:

// ingrain-ignore avoid-fetch-call: this endpoint streams the response body
// decisions-ignore D-0001: webhook replay needs raw fetch
const res = await fetch(url);

Without a reason it doesn’t count. On the line above, only a line that is just the comment counts. An agent adding one is asked to get the person’s approval, and CI shows every override on added lines as a warning annotation. Overrides are logged; ingrain rules promote and ingrain decisions stale flag rules and decisions that are overridden often.

CI

# .github/workflows/ingrain.yml
on: pull_request
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: WispAgents/ingrain/action@v0.4.0

The action runs ingrain check --diff base...HEAD --format github: hits become annotations on the pull request and a failing check. See where checks run for how the base revision is used.

CLI reference

This document contains the help content for the ingrain command-line program.

ingrain

Keep coding agents in line with what your team decided: recorded decisions and rules learned from your corrections, enforced at edit time, before commit and in CI

Usage: ingrain [OPTIONS] <COMMAND>

Setting up a repo (for coding agents):
  1. ingrain init --agents-md          hooks, pre-commit, and an AGENTS.md section for hookless agents
  2. ingrain decisions extract --doc AGENTS.md --no-git --no-github --no-sessions
                                       propose decisions from the rule docs (add --doc for each)
  3. Add a `checks:` block (forbid_deps, forbid_imports, forbid_patterns) to each proposal in
     decisions/pending/ that can be checked mechanically; without checks a decision never blocks
  4. Show the user the proposals, then `ingrain decisions accept <P-ids>` for the ones they approve
     and `ingrain decisions reject <P-id> --reason ...` for the rest
  5. On GitHub, add .github/workflows/ingrain.yml using WispAgents/ingrain/action
  6. Commit decisions/, .corrections/, .claude/settings.json and AGENTS.md on a branch
Until that first commit, ingrain's hooks let the agent accept and commit, when each runs as its
own command (no `cd`, variables or other programs in it); after it, agents only propose
(`ingrain decisions add --propose`, `ingrain decisions supersede`) and a person accepts.
Just for the user, nothing committed: `ingrain init --local` (this repo, .git/ingrain/local) or
`ingrain init --global` (every repo, ~/.config/ingrain); then `ingrain --local|--global decisions
add --propose ...`. A person accepts; there is no first-setup exception for personal stores.
Guide: https://github.com/WispAgents/ingrain/blob/main/skills/ingrain-setup/SKILL.md

Subcommands:

  • init — Create .corrections/ and decisions/, and install the Claude Code and git hooks (--local: for you only, nothing committed; --global: for every repository)
  • check — Check added lines against learned rules and decisions (pre-commit, CI)
  • decisions — The decision ledger: record, extract, review, supersede and list decisions
  • rules — Learned lint rules: mine corrections, propose, review, promote and evaluate rules
  • viewer — Open the desktop viewer: review proposals, read decisions and rules with their history (--local / --global: only that store)
  • hook — Claude Code hook entry point (reads the hook JSON on stdin)

Options:

  • --repo <DIR> — Repository to work on (defaults to the current directory)
  • --local — Keep decisions and rules for this repository only, inside .git/: never committed
  • --global — Keep decisions and rules for every repository on this machine (~/.config/ingrain, or $INGRAIN_HOME)

ingrain init

Create .corrections/ and decisions/, and install the Claude Code and git hooks (--local: for you only, nothing committed; --global: for every repository)

Usage: ingrain init [OPTIONS]

Options:

  • --no-claude — Don’t touch the Claude Code settings
  • --no-git-hook — Don’t install the git pre-commit hook
  • --agents-md — Also add an ingrain section to AGENTS.md, for agents that read it but run no hooks (Codex, Cursor, Copilot…)

ingrain check

Check added lines against learned rules and decisions (pre-commit, CI)

Usage: ingrain check [OPTIONS] [PATHS]...

Arguments:

  • <PATHS> — Files to check (default: every file with added lines)

Options:

  • --staged — Check staged changes (pre-commit)

  • --diff <RANGE> — Check added lines in a revision range, e.g. origin/main...HEAD (CI)

  • --format <FORMAT>

    Default value: text

    Possible values: text, json, github

ingrain decisions

The decision ledger: record, extract, review, supersede and list decisions

Usage: ingrain decisions <COMMAND>

Subcommands:

  • add — Record a decision (accepted, or --propose for review)
  • extract — Propose decisions from rule docs, commits, GitHub PRs/reviews/issues and Claude Code sessions
  • review — Go through proposed decisions one by one: accept, edit, reject or skip
  • accept — Accept proposals; a superseding proposal retires the decision it replaces
  • reject — Reject a proposal so extraction doesn’t bring it back
  • supersede — Propose a replacement for an accepted decision
  • list — List decisions (--all includes superseded ones and proposals)
  • show — Show one decision in full
  • for — Decisions that apply to a file
  • stale — Decisions whose scope no longer exists, that are often overridden, or that are broken

ingrain decisions add

Record a decision (accepted, or --propose for review)

Usage: ingrain decisions add [OPTIONS] <DECISION>

Arguments:

  • <DECISION> — The decision, as one imperative sentence

Options:

  • --reason <REASON>

  • --scope <SCOPE> — Path globs or symbol names it applies to (repeatable). Omit for repo-wide

  • --category <CATEGORY>

    Default value: convention

  • --rejected <REJECTED> — An alternative that was rejected (repeatable)

  • --forbid-import <FORBID_IMPORT> — Module that must not be imported in scope (repeatable)

  • --forbid-dep <FORBID_DEP> — Package that must not be added as a dependency (repeatable)

  • --forbid-pattern <FORBID_PATTERN> — ast-grep pattern that must not appear in scope, as Language:pattern (repeatable)

  • --source <SOURCE> — Link to where it was decided (repeatable)

  • --propose — Write it as a proposal for a human to accept (what agents should use)

ingrain decisions extract

Propose decisions from rule docs, commits, GitHub PRs/reviews/issues and Claude Code sessions

Usage: ingrain decisions extract [OPTIONS]

Options:

  • --since <SINCE> — Only texts after this date (YYYY-MM-DD). Default: 90 days before the first run

  • --github <GITHUB> — GitHub repo as owner/name (default: detected from the remote; skipped if there is none)

  • --no-github

  • --no-git

  • --no-sessions

  • --doc <DOC> — Also read a doc that states project rules, e.g. AGENTS.md (repeatable). Read once

  • --sessions-dir <SESSIONS_DIR> — Claude Code projects directory (default ~/.claude/projects)

  • --pages <PAGES> — Pages of 100 GitHub items per stream

    Default value: 10

  • --max-texts <MAX_TEXTS> — Read at most this many texts per run (oldest unread first)

    Default value: 400

  • --llm <LLM> — auto, claude, api or none

    Default value: auto

  • --model <MODEL>

  • --dry-run — Count the texts and stop before calling the model

ingrain decisions review

Go through proposed decisions one by one: accept, edit, reject or skip

Usage: ingrain decisions review

ingrain decisions accept

Accept proposals; a superseding proposal retires the decision it replaces

Usage: ingrain decisions accept <IDS>...

Arguments:

  • <IDS>

ingrain decisions reject

Reject a proposal so extraction doesn’t bring it back

Usage: ingrain decisions reject --reason <REASON> <ID>

Arguments:

  • <ID>

Options:

  • --reason <REASON>

ingrain decisions supersede

Propose a replacement for an accepted decision

Usage: ingrain decisions supersede [OPTIONS] --decision <DECISION> --reason <REASON> <ID>

Arguments:

  • <ID> — The accepted decision to replace

Options:

  • --decision <DECISION> — The new decision
  • --reason <REASON>
  • --scope <SCOPE> — New scope (default: the old decision’s scope)
  • --keep-checks — Keep the old decision’s deterministic checks

ingrain decisions list

List decisions (--all includes superseded ones and proposals)

Usage: ingrain decisions list [OPTIONS]

Options:

  • --all

ingrain decisions show

Show one decision in full

Usage: ingrain decisions show <ID>

Arguments:

  • <ID>

ingrain decisions for

Decisions that apply to a file

Usage: ingrain decisions for [OPTIONS] <PATH>

Arguments:

  • <PATH>

Options:

  • --json

ingrain decisions stale

Decisions whose scope no longer exists, that are often overridden, or that are broken

Usage: ingrain decisions stale

ingrain rules

Learned lint rules: mine corrections, propose, review, promote and evaluate rules

Usage: ingrain rules <COMMAND>

Subcommands:

  • mine — Capture corrections from git history, PR review suggestions and agent transcripts
  • propose — Cluster corrections and write backtested rule proposals to .corrections/pending/
  • review — Go through proposed rules one by one: accept, edit, reject or skip
  • accept — Accept proposed rules (moves them to .corrections/rules/ and stages them)
  • reject — Reject a proposed rule so it is never proposed again
  • list — List accepted and proposed rules with their mode and hit counts
  • mode — Set a rule’s mode by hand
  • promote — Suggest (or apply) promotions and demotions from the hit log
  • eval — Time-split evaluation: learn from older corrections, score on newer ones

ingrain rules mine

Capture corrections from git history, PR review suggestions and agent transcripts

Usage: ingrain rules mine [OPTIONS]

Options:

  • --github <GITHUB> — Also read ```suggestion review comments from GitHub (owner/name, or detected from the origin remote when given without a value)

  • --review-pages <REVIEW_PAGES> — Pages of 100 review comments to read, newest first

    Default value: 20

  • --pr-refs — Fetch refs/pull/*/head first, so fix-ups inside PRs survive squash merges

  • --transcripts <TRANSCRIPTS> — Read Claude Code transcripts from this projects directory (default ~/.claude/projects)

  • --no-transcripts — Skip transcripts

  • --since <SINCE> — Only commits after this date (git log --since)

  • --max-commits <MAX_COMMITS> — Only the newest N commits

ingrain rules propose

Cluster corrections and write backtested rule proposals to .corrections/pending/

Usage: ingrain rules propose [OPTIONS]

Options:

  • --llm <LLM> — Model backend for clusters templates can’t express: auto, claude, api or none

    Default value: auto

  • --model <MODEL> — Model id (default claude-opus-5-5)

  • --llm-clusters <LLM_CLUSTERS> — Clusters sent to the model at most

    Default value: 10

  • --min-corrections <MIN_CORRECTIONS> — Corrections of the same pattern needed before a rule is proposed (default: min_support in .corrections/config.yml, 1 unless set). Raise it for fewer, better-supported rules

  • --explain — Print every cluster and how each candidate rule scored

  • --all — Also keep single-fix rules that look like one-offs (code still common today, or a generic name)

ingrain rules review

Go through proposed rules one by one: accept, edit, reject or skip

Usage: ingrain rules review

ingrain rules accept

Accept proposed rules (moves them to .corrections/rules/ and stages them)

Usage: ingrain rules accept <IDS>...

Arguments:

  • <IDS>

ingrain rules reject

Reject a proposed rule so it is never proposed again

Usage: ingrain rules reject --reason <REASON> <ID>

Arguments:

  • <ID>

Options:

  • --reason <REASON>

ingrain rules list

List accepted and proposed rules with their mode and hit counts

Usage: ingrain rules list

ingrain rules mode

Set a rule’s mode by hand

Usage: ingrain rules mode <ID> <MODE>

Arguments:

  • <ID>
  • <MODE>

ingrain rules promote

Suggest (or apply) promotions and demotions from the hit log

Usage: ingrain rules promote [OPTIONS]

Options:

  • --apply

ingrain rules eval

Time-split evaluation: learn from older corrections, score on newer ones

Usage: ingrain rules eval [OPTIONS]

Options:

  • --split <SPLIT> — Share of corrections (oldest first) used to learn rules

    Default value: 0.6

  • --llm <LLM> — Model backend for clusters templates can’t express: auto, claude, api or none

    Default value: none

  • --model <MODEL>

  • --llm-clusters <LLM_CLUSTERS>

    Default value: 10

  • --min-corrections <MIN_CORRECTIONS> — Corrections of the same pattern needed before a rule is proposed (default: min_support in .corrections/config.yml, 1 unless set). Raise it for fewer, better-supported rules

  • --json <JSON> — Write the full report as JSON

ingrain viewer

Open the desktop viewer: review proposals, read decisions and rules with their history (--local / --global: only that store)

Usage: ingrain viewer [OPTIONS] [PATH]

Arguments:

  • <PATH> — A folder inside the repository to open (default: the current directory, or --repo)
  • <RUNE> — Rune’s own flags for headless runs (-- --snap out.png --scene timeline); implies --wait

Options:

  • --select <ID> — Open on this item, e.g. D-0004 or a rule id
  • --wait — Keep the terminal until the window closes

ingrain hook

Claude Code hook entry point (reads the hook JSON on stdin)

Usage: ingrain hook [OPTIONS] <EVENT>

Arguments:

  • <EVENT>

    Possible values: session-start, pre-tool-use, post-tool-use, stop

Options:

  • --from-plugin — Set by the Claude Code plugin; does nothing when the repo’s own settings run ingrain

Decision file format

One YAML file per decision, decisions/D-0001.yml, reviewed like code:

id: D-0001
decision: Billing code calls the payments client, never raw fetch.
reason: the client adds idempotency keys
rejected:
- a shared fetch wrapper per module
scope:
- src/billing/**          # path globs, or symbol / module names like `apiClient`
category: convention      # convention | constraint | api_change | architecture | scope
status: accepted          # accepted | superseded (proposals live in decisions/pending/)
checks:                   # optional; without checks a decision is shown, not enforced
  forbid_imports: [axios]
  forbid_deps: [redis]    # package.json, pyproject.toml, requirements*.txt, Cargo.toml, go.mod
  forbid_patterns:
  - language: TypeScript
    pattern: fetch($$$A)  # ast-grep pattern
sources:
- https://github.com/acme/app/pull/214
FieldMeaning
idD-NNNN once accepted; proposals in decisions/pending/ use P-… ids
decisionThe rule, as one sentence
reasonWhy; shown to the agent next to the decision
rejectedAlternatives considered and turned down
scopePath globs, or symbol / module names. No scope, or **, is repo-wide
categoryconvention, constraint, api_change, architecture or scope
statusaccepted or superseded
checksOptional. Without checks a decision is shown, not enforced
sourcesWhere the decision came from (PRs, docs, commits)

Agents never edit these files. They propose with ingrain decisions add --propose or ingrain decisions supersede, and a person accepts with ingrain decisions review.

Repository layout

decisions/D-NNNN.yml       accepted decisions          committed
decisions/pending/         proposed decisions          gitignored
.corrections/rules/        accepted learned rules      committed
.corrections/pending/      proposed rules              gitignored
.corrections/config.yml    thresholds, agent markers   committed
.git/ingrain/              corrections, hit logs, hook sessions, extraction state (local)

Personal stores (local and global) use the same layout under their own directory, with corrections/ in place of .corrections/. They are never committed:

.git/ingrain/local/                   --local: this repository only (shared by its worktrees)
  decisions/L-NNNN.yml                accepted decisions
  decisions/pending/                  proposed decisions
  corrections/rules/                  accepted learned rules
  corrections/pending/                proposed rules
  corrections/config.yml              thresholds, agent markers
~/.config/ingrain/                    --global: every repository ($INGRAIN_HOME overrides)
  decisions/G-NNNN.yml
  corrections/rules/
  ...
.claude/settings.local.json           hooks from `init --local` (added to .git/info/exclude)
~/.claude/settings.json               hooks from `init --global` ($CLAUDE_CONFIG_DIR overrides)

Contributing

cargo fmt --all --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --all --locked

Crates: core (data model, rule files, git), engine (ast-grep), learn (capture, cluster, rule writing, backtest, eval), ledger (decisions, scope, checks, extraction), cli (the ingrain binary). PLAN.md is the working plan.

See CONTRIBUTING.md before opening a PR, SECURITY.md to report a vulnerability, and CHANGELOG.md for release notes. This project follows a Code of Conduct.

License: Apache-2.0.

Docs

This book lives in docs/book/. The CLI reference is generated from the clap definitions; regenerate it after changing a command or flag:

cargo run -q -p ingrain -- --markdown-help > docs/book/src/reference/cli.md
mdbook serve docs/book   # http://localhost:3000

CI fails when reference/cli.md is out of date. Pushes to main deploy the book to GitHub Pages.