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

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.