planlog

Treat your Claude Code plans like database migrations.

planlog is a Claude Code plugin that auto-captures plan-mode output into immutable, repo-local revisions. Reviewers see both implementation changes and the accepted plan that shaped them.

Why this is important

AI coding sessions often drop planning context once implementation starts. That causes review and maintenance gaps:

• What is the design?
• Why this design?
• What decision trail led to this diff?

planlog turns plan reasoning into durable project history.

What the plugin does

• Hooks Claude Code Stop and SessionEnd events
• Discovers plan artifacts from Claude plan files and transcripts
• Captures accepted/proposed plans into plans/revisions/*.md
• Maintains linear history with .head, index.json, and head_version
• Deduplicates by stable fingerprint to avoid duplicate records
• Verifies chain integrity with planlog verify

Install in 60 seconds

Prerequisites:

• Claude Code installed and authenticated
• A git repository (capture is repo-scoped)
• Go is optional. planlog first uses an existing binary from PATH, then tries the plugin bundle, then builds from source. The bundled binary in this repo is currently macOS arm64; other platforms typically need Go or PLANLOG_BIN.

Install:

claude plugin marketplace add https://github.com/lu-zhengda/planlog
claude plugin install planlog@planlog

That is enough for zero-manual capture in git repositories.

Quick verification

planlog head --plans-dir plans
planlog history --plans-dir plans --limit 10
planlog verify --plans-dir plans

How data is stored

plans/
  .head
  index.json
  revisions/
    20260220_230519_plan-starry-gliding-sparkle.md

index.json key fields:

• schema_version: index format version
• head: current revision id
• head_version: total revision count in the linear chain
• fingerprints: dedupe map for idempotent capture

Configuration

• PLANLOG_BIN: explicit planlog binary path
• PLANLOG_PLANS_DIR: custom plans directory (default plans)
• PLANLOG_HOOK_POLICY: every-plan-event (default) or accepted-only

Known limitations

• Capture depends on Claude plan-mode artifacts. If a task is executed without entering plan mode, there is no plan artifact to migrate.
• The hook processes one best candidate per hook invocation. Selection is ordered by score first, then newest timestamp. In multi-plan sessions, this is usually the latest accepted plan (often from ~/.claude/plans) at that moment; it does not backfill every prior plan from that session in a single run.

CLI (debug/admin)

planlog candidates --source claude --for-cwd "$(pwd)"
planlog capture --source claude --for-cwd "$(pwd)"
planlog show head --plans-dir plans
planlog verify --plans-dir plans

Developer setup

go build -o ./bin/planlog ./cmd/planlog
go test ./...

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.