io.github.promptwheel-aiPublished by GitHub account promptwheel-aiv0.8.0Updated Nov 6, 2026
Git-history memory for coding agents: reverts, weakened tests, hot spots, and unreviewed notes.
Turns a repository's Git history into memory an assistant can read: hotspots, reverted approaches, suppressed tests, and durable notes.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
Git history is large. When coding agents do not inspect it, they can re-propose approaches a repository already rejected.
Logbook turns a repository's Git history into memory an agent can use: a deterministic recall layer (hotspots, reverted approaches, suppressions, assertion weakening, and bounded history queries) plus durable notes an agent writes down after it investigates why a change happened.
Everything runs locally. The CLI has zero npm dependencies, reads raw Git objects for evidence checks, and never sends repository data anywhere. Node.js 18 or newer is required.
init analyzes the repo, writes the history artifacts, and installs a compact
workflow in AGENTS.md, CLAUDE.md, or .cursorrules so the agent reads
history before it plans: read LOGBOOK.md, page each task path with
context --file, verify leads with git show, refresh, audit, and
annotate what it verified. The same workflow ships as an agent skill in
plugin/skills/logbook/SKILL.md.
Its output, shortened:
The examples below use logbook as the binary name. Run them through the exact
package above, or install @promptwheel/logbook@latest locally or globally.
context returns history in pages of at most 20 events and 8 KiB; repeat the
identical filters with each NEXT cursor until END complete.
When an agent investigates why a prior change happened during real work, it can preserve the result immediately, with no prompt or human gate:
The note is durably appended to annotations.jsonl and appears in
LOGBOOK.md before the command exits. It is always labeled machine-authored
and unreviewed and is bounded in the startup digest. An optional exact quote
can be attached with --span, --side, and (for diff evidence)
--evidence-file; a quote that does not ground in raw Git objects is rejected
rather than guessed.
Commit annotations.jsonl to share the notes with the team, or add it to
.gitignore to keep them local to one checkout.
context preserves filtered query order but emits pages of at most 20 events
and 8 KiB. A cursor is bound to the repository HEAD, filters, analysis window,
and ordered event set, so a stale or edited cursor is rejected instead of
silently drifting.
The history scan is cached in bounded windows. On a history of tens of
thousands of commits a cold run takes tens of seconds, a warm run that reuses
the ledger on disk is well under a second, and a repeat call with an unchanged
HEAD in an MCP session is milliseconds. LOGBOOK_NO_CACHE=1 forces a rebuild;
LOGBOOK_WINDOW=N tunes the window.
In a random 400-repo sample of the top 2,500 GitHub repositories, the median
LOGBOOK.md was about 1,000 estimated tokens while the median full git log
was 82× larger. See context economics and the
bounded context format.
Three surfaces over the same deterministic history layer:
logbook query --json (filtered, 200 rows unless you pass --limit) and
logbook --json (the full ledger) emit JSONL you can shell from any language. logbook audit --json returns the live suppressions as one array. The JSON is cache-invariant (byte-identical
with and without LOGBOOK_NO_CACHE=1), so it is safe to parse in CI.@promptwheel/logbook-mcp (bin logbook-mcp) serves the history to an agent
over the Model Context Protocol: a Claude Code or other MCP client reads hotspots,
do-not-retry reverts, and suppression signals without shelling anything.queryEvents,
analyze, auditHead, and hotspots are exported for advanced in-process use; the scan and
cache entry points take explicit options, so the CLI and MCP are the first-class surfaces for
most integrations.The paired check engine, promptwheel, has the matching surface. Both are described in its INTEGRATE.md.
An internal six-task planning experiment on history-dense repos found that
agents without history re-proposed already-tried or already-finished work in
4 of 6 repos and 0 of 6 with LOGBOOK.md in context, at about 4.7k extra plan
tokens. A later sealed held-out screen on ten new tasks found no advantage over
a strong raw-Git instruction, and traced the gap to retrieval rather than the
index. The calibrated claim is: valuable on sufficiently difficult,
history-dense tasks; not universally better. Details and limits are in
wrong-work-benchmark.md and
does-it-change-agent-behavior.md.
logbook --help lists every filter and option.
0.11.0 removes logbook refine, logbook journey, and --out. Both commands
now fail with not a git repository, and --out is an unknown option.
Artifacts always go to the repository root. The analyze result no longer
carries first, last, threshold, mentor, abyss, winter, or trials,
and renderJourneyAnsi, journeyBeats, almanacStats, GATE_PAT, and
MENTOR_PAT are no longer exported. The event and --json shapes, the five MCP
tools, and doctor did not change. MCP server 0.8.0 requires this core.
0.10.0 removed the experimental reviewed-decision layer and the OKF export:
annotate-draft, pending, accept/accept-draft, accept-lead,
reject-lead, check, publish, outcomes, and export. Files that layer left
behind (.logbook/, decision-cards.jsonl, annotation-reviews.jsonl) are
ignored and can be deleted by hand.
From any release, a normal refresh rewrites a ## Repo memory block that an
earlier release generated, so doctor passes after an upgrade. User-edited
blocks are never touched. Existing annotations.jsonl rows stay unreviewed
digest notes. A JOURNEY.md left by a release before 0.9.7 is ignored and can
be deleted. If 0.8 wrote annotations to a custom directory, move that
annotations.jsonl to the repository root. Earlier notes are in the git history
of this file.
Logbook tells you what history says. promptwheel is the check that verifies whether today's claimed improvement came from the code rather than moving the goalposts.
Apache 2.0.
Source: README.md at commit acf69e2
The repo's history digest: hotspots, do-not-retry reverts, suppression ledger, fragile areas, notable events, per-file history. Use when starting work in an unfamiliar repo, before a refactor or large change, or when deciding whether green tests can be trusted.
repoPersist a machine-authored, explicitly unreviewed note after investigating a commit. It appears immediately in the repo digest. Optional quoted evidence is raw-object verified.
bysharequiredwhyrequiredreposidespanevidenceFileWhat is STILL suppressed in HEAD and since when (blame-dated), with re-silencing fight logs. Use when asked what tests are skipped, what debt is live, or whether a suppression keeps coming back.
repoFilter the full commit-event record with precision. Start with all relevant files + event type before broad grep. Repeated paths use OR; other filters use AND. Returns up to `limit` matches, default 100, with exact counts and explicit truncation recovery.
filegreprepofileslimitsinceuntilrevertweakensuppressdowngradeReturn the same filtered history order as logbook_query in compact, bounded pages for agent context. Pass all relevant paths in files; paths use OR and other filters use AND. This is deterministic delivery, not relevance ranking. Repeat identical filters with every NEXT cursor until END complete when completeness matters.
filegreprepofilessinceuntilcursorrevertweakensuppressdowngrade90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
npx -y @promptwheel/logbook@latest init 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 eventslogbook # refresh the history artifactslogbook context --file src/cache.ts --revert # bounded history for a pathlogbook audit # what is still suppressed, and since whenlogbook query --json --file src/cache.ts # the same events as JSONLlogbook doctor # read-only artifact and wiring healthlogbook annotate <commit> "why this approach was rejected" --by codexlogbook init [path]logbook [path] [--json]logbook audit [path] [--json [--file P ...] [--ref REF]]logbook doctor [path]logbook query [path] [filters] [--json]logbook context [path] [filters] [--cursor TOKEN]logbook annotate SHA "WHY" [optional evidence] [--by WHO]