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 extractproposes 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 indecisions/. - Lint rules learned from your corrections: when you keep fixing the same thing in agent code,
ingrain rules mineandingrain rules proposeturn 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
- New here? Install ingrain and follow the quick start.
- Using Claude Code, Codex, Cursor or another agent? See Use it from your coding agent.
- Not sure which kind of rule you need? Read Decisions or learned rules?.
- Looking for a flag? The CLI reference is generated from the binary itself.
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
| Skill | Use it for |
|---|---|
ingrain-setup | Install 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-rules | Learn 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?
| Decision | Learned rule | |
|---|---|---|
| Comes from | Someone saying what code must do, recorded or extracted | A mistake people kept fixing in agent code, mined from history |
| Holds | A sentence, a reason, a scope, optional checks | An ast-grep pattern, backtested on past corrections |
| Covers | Anything: architecture, conventions, dependencies, scope | Only code patterns a lint rule can match |
| Enforced | Shown before edits in scope; with checks, a breaking edit is denied before it lands | Runs after edits, in shadow → warn → block mode, promoted from its hit log |
| Changed with | ingrain decisions supersede | ingrain rules mode, ingrain rules promote |
| Per-line override | A 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
| Source | Signal |
|---|---|
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 transcripts | The 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:
| Store | Where | Applies to | Decision ids |
|---|---|---|---|
| project (default) | decisions/, .corrections/ | the repository, shared with the team | D-0001 |
--local | .git/ingrain/local/ | this repository, for you only | L-0001 |
--global | ~/.config/ingrain/ | every repository on this machine | G-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.jsonorsettings.local.jsonalready 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 listanddecisions staleread 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 acceptrefuses an id another store already has. - Writes go to one store.
--local/--globalgo right afteringrain, before the command (ingrain --global decisions add …). Without a flag, ingrain writes to the project store when the repo hasdecisions/or.corrections/. Otherwise it writes to the local store onceinit --localhas run. Learned-rule commands (rules propose,review,accept,reject,mode,promote) use the flag the same way.rules minestays per repository. - Ids pick the store.
decisions supersede G-0001puts the proposal in the global store.decisions accept,rejectandshowfind the store from the id, so they need no flag.decisions reviewshows 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 initoringrain init --localrun 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.ymlandrejected.yml. They can’t accept, reject or retune them either, and can’t runinit --local/init --global, without asking you. Proposals inpending/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-andG-ids are your personal decisions, and to record a decision with--globalwhen 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.
| Key | Does |
|---|---|
A | Accept |
R | Reject. Type why, then Return. Extraction won’t propose it again. |
J / K | Next / previous |
| Esc | Cancel 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
| Key | Does |
|---|---|
| ⌘1 … ⌘6 | Inbox, Decisions, Learned rules, Timeline, Applies to, Archive |
↑ ↓ or J K | Move through the list |
/ or ⌘F | Filter |
| ⌘O | Open a repository |
| ⌘R | Reload |
| ⇧⌘B | Show 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.
| Hook | What happens |
|---|---|
SessionStart | Repo-wide decisions go into the session, plus how to propose a new one |
PreToolUse on Edit / Write / MultiEdit / NotebookEdit | The 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 Bash | A 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 / Bash | Learned 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 |
Stop | Rules 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.
| Path | Command | On a hit |
|---|---|---|
| Commit | ingrain check --staged (.git/hooks/pre-commit) | the commit fails |
| Pull request | ingrain check --diff base...HEAD --format github (action) | annotations; failing check |
| By hand | ingrain 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 decisionsrules— Learned lint rules: mine corrections, propose, review, promote and evaluate rulesviewer— 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:
textPossible 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--proposefor review)extract— Propose decisions from rule docs, commits, GitHub PRs/reviews/issues and Claude Code sessionsreview— Go through proposed decisions one by one: accept, edit, reject or skipaccept— Accept proposals; a superseding proposal retires the decision it replacesreject— Reject a proposal so extraction doesn’t bring it backsupersede— Propose a replacement for an accepted decisionlist— List decisions (--allincludes superseded ones and proposals)show— Show one decision in fullfor— Decisions that apply to a filestale— 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, asLanguage: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 asowner/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 streamDefault 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 noneDefault 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 transcriptspropose— Cluster corrections and write backtested rule proposals to .corrections/pending/review— Go through proposed rules one by one: accept, edit, reject or skipaccept— Accept proposed rules (moves them to .corrections/rules/ and stages them)reject— Reject a proposed rule so it is never proposed againlist— List accepted and proposed rules with their mode and hit countsmode— Set a rule’s mode by handpromote— Suggest (or apply) promotions and demotions from the hit logeval— 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 firstDefault value:
20 -
--pr-refs— Fetchrefs/pull/*/headfirst, 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 noneDefault value:
auto -
--model <MODEL>— Model id (default claude-opus-5-5) -
--llm-clusters <LLM_CLUSTERS>— Clusters sent to the model at mostDefault value:
10 -
--min-corrections <MIN_CORRECTIONS>— Corrections of the same pattern needed before a rule is proposed (default:min_supportin .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 rulesDefault value:
0.6 -
--llm <LLM>— Model backend for clusters templates can’t express: auto, claude, api or noneDefault 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_supportin .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-0004or 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
| Field | Meaning |
|---|---|
id | D-NNNN once accepted; proposals in decisions/pending/ use P-… ids |
decision | The rule, as one sentence |
reason | Why; shown to the agent next to the decision |
rejected | Alternatives considered and turned down |
scope | Path globs, or symbol / module names. No scope, or **, is repo-wide |
category | convention, constraint, api_change, architecture or scope |
status | accepted or superseded |
checks | Optional. Without checks a decision is shown, not enforced |
sources | Where 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.