01
The Decision You Already Made Twice
You refactored the auth layer six months ago for a reason. Now you can't remember why. The code looks "wrong" to your new self, so you change it back. Three weeks later you remember the reason the hard way.
Developer Friction Logger
Stop losingyour thinkingto the void
Grít is a CLI tool that turns your commits into a knowledge base. By introducing small, purposeful friction at the moments that matter - a commit, a dependency, a revert - it captures the thinking behind your code, not just the code itself.
Hooks always exit 0
Local-first SQLite
Watcher is opt-in
$ grit init
✓ Installed pre-commit hook
✓ Created .grit/store.db
✓ Wrote .grit.yaml config
$ git commit -m "feat: add auth middleware"
→ What's the hardest part of this change?
[design] not sure if this belongs in the handler or middleware
→ What assumption are you most uncertain about?
token expiry — I haven't tested refresh edge cases yet
✓ Friction logged. Commit proceeding...
The Problem
The knowledge you need most
is the first thing you lose
grít is built for the moments that never make it into git history: the wrong turns, the uncertain assumptions, the AI paste you didn't fully internalize, the revert you don't want to talk about.
02
The AI Paste You Don't Quite Understand
You pasted 50 lines from ChatGPT. It works in tests. You ship it. Two months later it breaks in production and you have no memory of what it was supposed to do or why you trusted it.
03
The Revert With No Post-Mortem
You git revert a commit that broke prod. No one writes down what went wrong. No one captures what would have caught it. The same pattern ships again in three sprints.
04
The 40-Minute Rabbit Hole
You open auth.go to fix one thing. Forty minutes later you're somewhere deep in the call stack and the original problem is still open. No breadcrumb. No record. Just fatigue.
05
The Vague Name That Survived Code Review
handleData, result, tmp — they slip through review because everyone's looking at logic, not names. Six months later no one knows what "data" means in this context.
06
The Complexity That Crept In
One conditional became five. Nobody noticed because each addition was "just a small change." Now your cyclomatic complexity is 24 and nobody wants to touch it.
Design Philosophy
Stop avoiding friction.
Start embracing it.
As engineers, we're obsessed with speed. We automate everything to reach zero friction which often leads to zero reflection. grít turns the “moments of resistance” into your most valuable creative signals.
01Cognitive
Capture the struggle
The moment you hesitate is the moment you're actually learning. grít captures the “why” behind the hard decisions before the context disappears into the void.
02Mechanical
Purposeful Pause
A deliberate prompt after a large AI paste or a 40-minute rabbit hole isn't a hurdle — it's a guardrail that ensures your codebase remains an intentional investment.
03Social
Audit Trail of Thought
Commit messages document what changed. grít documents what you were thinking. Build a searchable timeline of your evolution as an engineer.
“The best time to document a decision is the moment you're making it.”
“Friction at the right moment is the difference between a commit message and an audit trail.”
How it works
Three surfaces. One timeline.
No new dashboard. grít lives where the work happens — commits, edits, and end-of-day review. Every signal becomes a searchable note.
At every commit
grít intercepts the pre-commit hook and asks adaptive, context-aware questions. Large diffs get split-commit prompts. New files get contract questions. Revert commits trigger a full 3-question post-mortem.
Capabilities
Everything grít does, automatically
Not telemetry. Not a team dashboard. The smallest prompts at the moments that matter — stored locally, queryable anytime.
- Adaptive Commit Interviews: Questions rotate from a configurable pool, avoiding repeats within a window. Context-aware: large diffs, new files, test-only changes, and config changes each trigger different questions.
- Real-time File Watcher: 200 ms debounced watcher catches paste events, large deletions, vague identifiers, complexity spikes, and dead time — all configurable.
- ADR-style Decisions: Record architectural decisions with a structured 4-question interview. Export to ADR markdown files. Never lose context on why you chose SQLite over Postgres.
- Analytics & Heatmaps: Weekly summaries, per-file complexity sparklines, 12-week GitHub-style heatmaps, and tag-grouped digests. Spot patterns before they become problems.
- Revert Post-Mortems: Every git revert automatically triggers a 3-question post-mortem. What went wrong? Was it caught in review? What would have caught it earlier?
- Portable Data Exports: Export everything to Markdown or JSON with date-range filters. Your friction data is stored locally in SQLite — no cloud, no lock-in, fully queryable.
- Snooze When You Need to Ship: grit snooze 30m pauses interviews without uninstalling hooks. Resume automatically or manually. Your CI never breaks — grít always exits 0.
- End-of-Day Reflection: Close the loop. See today's friction count, completed vs. skipped interviews, your consecutive-days streak, and answer two rotating reflection questions. Optionally export to dated markdown files.
Signals
What grít detects while you work
Small, timely moments of reflection. Every threshold is configurable in .grit.yaml.
AI Assist
≥ 15 new lines added
"Was any of this AI-assisted? What did you verify?"
Paste Check
≥ 30 new lines added
"Did you paste this? Do you fully understand what it does?"
Undo Spike
≥ 20 lines deleted
"Wrong turn or intentional cleanup?"
Dead Time
≥ 40 min in same file
"You've been in this file a while. Is the problem still clear?"
Naming
Vague identifier detected
"What would a better name be?"
Complexity
Score > 10.0
Per-function breakdown (informational)
Revert
git revert detected
3-question post-mortem
Quickstart
From install to first insight
Under a minute to your first logged friction event. Windows users need GCC for SQLite — that's the only gotcha.
Install
# macOS / Linux
go install github.com/alchemistreturns/grit@latest
# Windows (MSYS2 — needed for SQLite/GCC)
pacman -S mingw-w64-ucrt-x86_64-gcc
PATH="/c/msys64/ucrt64/bin:$PATH" \
go install github.com/alchemistreturns/grit@latestFirst build is slower (compiling SQLite). All subsequent builds are instant.
Initialize
cd your-project
grit initCreates .grit.yaml, .grit/store.db, and installs git hooks. Safe to re-run.
Work normally
# Terminal 1 — start the watcher
grit watch
# Terminal 2 — commit as usual
git commit -m "feat: add auth"Prompts appear at the right moments. Commits are never blocked — grít always exits 0.
Review your friction
grit reflect # end-of-day summary
grit stats week # 12-week heatmap + tags
grit log # searchable friction logTurn today's friction into a weekly pattern. Export to Markdown any time.
Open source