Every artifact has a grain. We've been ignoring half of every file for 70 years.
npx github:dev-sudeep018/grain
That's it. No install. No config. No daemon. No API key. Run it inside any git repository on Earth and it instantly reveals a dimension of your code that has been there the whole time and has never been visible.
When you build something, you pour attention into it — but the keystroke captures the residue, not the attention itself, and every act of building in the history of software has destroyed that signal at the moment of save.
Git records what changed. It throws away the shape of the attention that shaped it. The shape is recoverable. Nobody recovered it.
GRAIN recovers it.
Every other building craft reads grain. A carpenter reads wood grain to know where stress concentrated, where the tree fought wind, where it grew easy. A geologist reads stone grain. A musicologist reads the grain of a recording. A typographer reads the grain of a stroke. The metaphor is universal.
In every craft, grain is the visible residue of the act of making.
Code has grain too. We just never looked.
The reason no one looked is embarrassing in hindsight: we treated text as the
canonical form. Text is one projection of an artifact. The other projection
— where attention concentrated, where it skimmed, where it returned, where
it agonised, where it flowed — is the actual shape of the work. It lives
implicitly in git log, dispersed across thousands of timestamps and diffs,
and no tool ever pulled it back out as a unified property of the artifact.
GRAIN is that one missing primitive: a per-line attentional weight, reconstructable from history alone, attachable to any text artifact in any craft, queryable in five seconds, free forever.
Run grain inside any repository:
$ grain # repo overview — what's hot, what's bedrock
$ grain src/auth.js # per-line heatmap of one file
$ grain README.md # works on prose too — universal
$ grain --json src/auth.js # machine-readable, pipe to anything
Every line of every file gets:
- heat — blended recency × dwell, normalised within the file
- recency — how recent the last touch was
- dwell — total session-time attention invested
- last author / sha / summary — who shaped it and what they were doing
Cold blue lines are bedrock — old, stable, load-bearing. Molten red lines are where attention concentrated recently or repeatedly. The grain is where the truth is. Read those lines first.
Five-second mental model:
- Walk the file's commit log oldest → newest.
- For each commit, the gap to the previous commit (capped at 4h) is the attention spent in that session — the dwell. Cross-session returns count as a fixed re-engagement event.
git blameassigns each current line to the commit that last shaped it.- Each line inherits its commit's dwell, plus a uniform background share of total file dwell (because being part of a long-lived file is itself a form of attention).
- Heat = recency × 0.55 + dwell × 0.45, normalised per file.
It is the cheapest defensible reconstruction of the attentional history that git has been quietly carrying the whole time.
Once you can see the grain:
- Code review stops being uniform scrutiny. You read the molten lines first — that's where the recent fight happened, that's where bugs hide.
- Onboarding changes. A newcomer opens the file and immediately sees the bedrock (trust it) vs the live edge (ask about it).
- Refactoring has a target. Grain shows you which lines have been rewritten five times — those lines want to be a function.
- Reading other people's code becomes legible. Their grain is their taste. Where they spent attention is what they cared about.
- Trust in dependencies gains a new axis. A library with deep, even grain was crafted. A library with thin uniform grain was sprayed out.
GRAIN works on any text artifact tracked in git:
- prose drafts (where did the writer agonise?)
- design specs (which clauses were rewritten?)
- research notes (which equations grew slowly?)
- music notation, architectural drawings as svg, prompt files, configuration, anything text-shaped
The act of creation has the same shape across all of them.
npx github:dev-sudeep018/grain src/grain.js
You'll see the conservation-law comment block (cold — written once and held) sitting next to the heat-blending code (warmer — tuned, rewritten, tuned again). The grain reveals which decisions in the algorithm were made quickly and which were fought for.
git clone https://github.com/some/project
cd project
npx github:dev-sudeep018/grain
The repo overview surfaces three lists — hottest by churn, most recently touched, coldest bedrock. In thirty seconds you know which files are load-bearing, which are unsettled, and which are dead weight, without reading a single line of code.
You don't.
npx github:dev-sudeep018/grain
That fetches GRAIN directly from this repo and runs it. No npm install,
no global state, no permanent footprint. You can also clone and link:
git clone https://github.com/dev-sudeep018/grain
cd grain
npm link
grain
Requires Node 18+ and git on PATH. That's all.
grain repo overview (default)
grain repo repo overview (explicit)
grain <file> per-line grain for one file
grain show <file> same
grain --json [file] JSON output (pipe-friendly)
grain --no-tint <file> gutter-only color (no fg tint)
grain --top N limit overview rows (default 20)
grain --version
grain --help
NO_COLOR=1 disable color
FORCE_COLOR=1 force color through pipes
GRAIN_DEBUG=1 stack traces on error
- Not a linter. It does not say a line is bad.
- Not an AI assistant. There is no model, no API, no inference. It runs offline.
- Not a productivity tool. It does not speed up your workflow. It changes what you see when you look at a file.
- Not a metric for management. Grain is not a productivity score. Resist anyone who tries to use it that way. Grain is for the maker, not the manager.
- Not a daemon. Nothing watches you. Nothing phones home. Nothing is stored anywhere except your repo's existing git history.
MIT. Forever. Run it on anything. Fork it. Extend it. Build the next primitive on top of it.
If you've ever opened a file you wrote a year ago and felt the ghost of how hard one section was — GRAIN makes that ghost legible to anyone who opens the file after you.