logbook

Nobody reads the git history. It's too big — and skimming a slice gives you the wrong picture.

Every feature gets added by someone who can read the code but not the decisions behind it: the module that was rewritten three times, the approach that was tried and reverted, the "fix" last quarter that was actually a skipped test. AI assistants inherit that blindness on every session, in every repo. Code maps (Graphify and friends) tell them where things are, not what happened. The logbook mines the existing git history — up to the newest 20,000 commits — and writes the short version: the file your agent is told to read first.

npx -y @promptwheel/logbook init

One line: it reads the history, writes the brief, and wires your agent config (AGENTS.md, CLAUDE.md, or .cursorrules) so reading it is the default first step.

  1,326 commits · 322 files · 7.3 years · 354 authors

  ✓ wrote LOGBOOK.md     hotspots · do-not-retry · suppression ledger
  ✓ wrote events.jsonl   1,326 structured events
  ✓ wrote JOURNEY.md     the repo's story, told back to you

Single file. Zero npm dependencies. It never touches your source code or git history, and no repository data leaves your machine — it writes only its own brief files (and init adds a block to your agent config).

Why "logbook"

Because you need the SparkNotes of every decision that mattered in your git history, without pulling every book out of the library. And you couldn't anyway — for a third of the top repos on GitHub, the full log doesn't even fit in a context window. Your repo has been keeping the record for years; almost nobody reads it. This reads it back, and hands you the two pages that matter.

The three artifacts

| File | What it is | Who it's for | |---|---|---| | LOGBOOK.md | The brief a fresh session needs: hotspots, do-not-retry (reverted approaches), the suppression ledger (the times a test was skipped or a warning hushed), assertion-weakening events, fragile areas | Your agent. Drop it in context — CLAUDE.md can point at it | | events.jsonl | One structured event per analyzed commit: shape (src/test/config/docs), adds/dels, suppressions found in the diff, assertion deltas | Your tools. The data layer | | JOURNEY.md | Your repo's history as a hero's journey: The Call, The Threshold, The Abyss, The Long Winter, the Whispered Bargains | You. Run logbook journey to see it in color |

Usage

npx @promptwheel/logbook              # analyze the current repo
npx @promptwheel/logbook path/to/repo # or any repo
npx @promptwheel/logbook journey      # the story, in color (writes nothing)
npx @promptwheel/logbook journey --compare  # rank your almanac vs the top 2,500 GitHub repos
npx @promptwheel/logbook audit        # what is STILL suppressed in HEAD, and since when
npx @promptwheel/logbook context --file path/to/file --revert  # bounded, paged query view
npx @promptwheel/logbook annotate SHA "why it happened" --by WHO   # persist WHY a commit happened
npx @promptwheel/logbook --json       # events to stdout (writes nothing)

# era-scoped archaeology
npx @promptwheel/logbook --since 2024-01-01 --until 2025-01-01

Options: -n/--max N (commit cap, default 20000) · --compare · --out DIR · -q/--quiet

context preserves the filtered query order but serializes it into pages of at most 20 events and 8 KiB, with an opaque NEXT cursor and explicit END complete. It is a delivery format, not relevance ranking; use query when you need the raw JSONL interface. A cursor is bound to the repository HEAD, filters, analysis window, and ordered event set; if any changes, restart from the first page. On a default-window cold run, the CLI creates or refreshes events.jsonl after page one so NEXT pages reuse the scan; it never changes source or Git history. Non-default -n or --since/--until windows remain uncached, so each CLI page rescans that explicit window. Across 7,123 measured events, the 0.8 representation used 72.7% fewer bytes than the raw rows (method and scope).

The ledger is batched

The expensive part (scanning 20k commits of diffs) runs once, in bounded windows, and every consumer reuses it: if events.jsonl is present and matches HEAD it is loaded instantly; if new commits landed, only they are scanned and merged. Measured on a 20k-commit repo: 43s cold, 0.4s with a prior run on disk, 4ms on repeat calls in an MCP session. Escape hatches: LOGBOOK_NO_CACHE=1 forces a full rebuild; LOGBOOK_WINDOW=N tunes the scan window.

--compare uses a percentile table baked into the CLI from a 2,500-repo fleet run — still zero dependencies and zero network calls.

Wire it into your agent

logbook init does this for you. Manually, it's one block in your CLAUDE.md (or AGENTS.md / .cursorrules) so every fresh session is instructed to read the history first:

## Repo memory
Before planning or editing:
1. Read LOGBOOK.md at the repo root completely before any history query.
2. If Historical signal is LOW, use it only as a hotspot map. Otherwise,
   inspect task-relevant do-not-retry entries and fragile areas.
3. For completeness, query relevant paths before broad terms:
   npx -y @promptwheel/logbook query --file path/to/file --revert
   If output says TRUNCATED, narrow filters or raise --limit before concluding.
4. Treat findings as leads, not verdicts. Verify claims with git show SHA and
   confirm that the constraint still applies to the current tree.
Refresh the record: npx -y @promptwheel/logbook
Check what is still silenced: npx -y @promptwheel/logbook audit
When you investigate WHY a listed commit happened and verify it in the
diffs, persist it (replace SHA, the sentence, and MODEL with your own
model name; never annotate guesses):
npx -y @promptwheel/logbook annotate SHA "one specific sentence" --by MODEL

Wiring makes history the default first read instead of relying on the agent to invent git archaeology. It is still an instruction, not a guarantee; for high-risk work, confirm that the digest was actually consulted.

Lazy enrichment: the record says WHAT, your agent persists WHY

The ledger can tell you a refactor was reverted; it can't tell you it was reverted because webpack4 broke. Your agent figures that out anyway the first time a task collides with the revert — annotate keeps the finding instead of discarding it at session end:

logbook annotate c08adc2 "WeakMap cache added to dodge a React-Compiler lint warning; reverted to direct ref mutation" --by claude

LOGBOOK.md is updated immediately (a later session that finds fresh artifacts on disk may never re-run the CLI), and the do-not-retry entry carries the why:

- 2024-09-15 c08adc2 revert useShallow refactor in #2701 (#2703)
  - why (inferred by claude, 2026-07-11): WeakMap cache added to dodge a React-Compiler lint warning; reverted to direct ref mutation

Annotations live in annotations.jsonl — sha-keyed (immutable, so they never go stale as facts), attributed, dated, last write per commit wins. They are judgments layered on the record, never mixed into it: the deterministic ledger stays untouched, the whys render with provenance and a disclaimer. Measured on the A/B benchmark: an agent whose logbook carried the whys stated real failure causes as design constraints at plan time (+2% read tokens), where the un-enriched agent planned an investigation — and, on zustand, guessed the cause wrong. One caution: annotations age as constraints even though they never invalidate as facts — a "broke webpack4" reason stops binding once webpack4 is dead, so the date is always shown. Commit the file for a shared team memory, or gitignore it for a private one.

The audit: archaeology becomes a to-do list

logbook audit joins the ledger's dates with what is still true in HEAD:

  describe.skip  test/express.static.js:137  since 2019-05-02 (7.2y)

  1 live suppression · oldest 7.2 years

That is express, today: its static-file test suite has been skipped for seven years. The ledger tells you when it happened; the audit tells you it is still happening. And when a suppression has been removed and RE-added, the audit shows the fight log: re-silenced ×3 (+-++--+) — a test someone keeps trying to fix, and keeps losing to.

Context economics

The median top-2,500 repo's LOGBOOK.md is ~1,000 tokens. Its raw git log is 82× that — and for a third of repos the full log doesn't fit in a 150k context window at all. Measured across 400 repos: docs/context-economics.md.

Does it actually change agent behavior?

On history-dense tasks, measurably — with an honest boundary found by our own later testing: on a held-out sample of ten easier planning tasks, a well-instructed agent matched it using raw git alone, and the bottleneck was traced to the query/retrieval path (see the evidence-status note in docs/wrong-work-benchmark.md). In the original A/B test, an agent asked to plan a useShallow refactor in zustand walked straight into re-attempting a refactor that was merged and reverted in 2024. The same agent with LOGBOOK.md in context started from the revert, inferred the repo's characteristic failure class from the do-not-retry list, and planned to pin the old failure with a test first. Full transcripts: docs/does-it-change-agent-behavior.md.

In a six-task internal experiment across history-dense planning tasks, the un-wired agent proposed already-reverted or already-rejected work in 4 of 6 tasks; the wired agent in 0 of 6, for about +4.7k tokens of context. Method and honest scope: docs/wrong-work-benchmark.md.

Honest scope

• Findings are leads, not verdicts. A suppression commit means "a human should look here," not misconduct. Large assertion removals are usually feature deletions — they're tagged as such.
• Detection is regex over commit subjects and diffs (lineage: a calibrated classifier from a 1,800-PR study of agent-authored code). It will miss clever evasions and flag some innocents. That's the right trade for a zero-dependency tool that runs in seconds — and it's a deliberate division of labor: the logbook is the cheap, deterministic recall layer; the agent reading it is the precision layer that triages leads against the task.
• It reads what survived. Squash and rebase erase in-branch attempts (a tried-then-reverted change nets to zero in the squashed diff), and uncommitted experiments were never visible at all. The logbook complements an agent journaling during the work — annotate is the bridge for exactly that — it does not replace it.
• Shallow clones starve the analysis — the logbook will tell you to git fetch --unshallow.

The logbook records; the referee judges

This tool is one half of a pair. The logbook tells you a test was skipped in March. promptwheel — the referee — proves whether today's "win" came from the code or from editing the tests. Past tense and present tense of the same question: did this actually improve?

MIT.