Logbook MCP server

logbook

Coding agents often skip git history. It is large, and an arbitrary slice can give 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. Fresh agent sessions often start without those decisions. 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 a compact recall layer that your agent is instructed to consult.

npx -y @promptwheel/logbook init

One line: it reads the history, writes the brief, and adds a history workflow to your agent config (AGENTS.md, CLAUDE.md, or .cursorrules).

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 a compact index of the decisions its detectors can recover without pulling every book out of the library. In a random 400-repo sample of the top 2,500 GitHub repositories, 34% of full logs exceeded a 150k-token context estimate. Logbook turns that record into a bounded brief and verifiable leads; it does not claim complete decision recall.

The three artifacts

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 doctor       # read-only artifact/wiring/skill/query health check
npx @promptwheel/logbook context --file path/to/file --revert  # bounded, paged query view
npx @promptwheel/logbook context --file src/a.ts --file src/b.ts # multi-path OR query
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

Shortened. The full README is on GitHub.