lorekeep

Intercept AI-assisted git commits and enrich them with structured metadata — so other AIs (and humans) can later understand why changes were made, not just what changed.

Unlike tools that store AI context in external services or separate branches, lorekeep writes metadata directly into git commit trailers. This means provenance data travels with the commit — visible in git log, preserved across forks, and queryable without any extra tooling. Full session transcripts are optionally stored on a shadow git branch, keeping everything in git with zero external dependencies.

Quick Start

# Install into any repo — sets up git hook + Claude Code session capture
npx lorekeep

# That's it. AI-assisted commits now get trailers automatically,
# and full session transcripts are stored on a shadow git branch.

Works on Windows, macOS, and Linux. No bash dependency — the hook is pure Node.js.

How It Works

┌─────────────────────────────────────────────┐
│  AI Tool (Claude Code / Copilot / Cursor)   │
│  Sets env: CLAUDECODE=1 / CURSOR_AGENT=1   │
│  Optionally writes .git/ai-context.json     │
└──────────────────┬──────────────────────────┘
                   │ git commit
                   ▼
┌─────────────────────────────────────────────┐
│  prepare-commit-msg hook (Node.js)          │
│  1. Detect AI involvement (env/heuristic)   │
│  2. Read rich context from ai-context.json  │
│  3. Append trailers via git interpret-trailers│
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│  Commit with AI trailers:                   │
│  AI-Tool: claude-code                       │
│  AI-Model: claude-sonnet-4-6                │
│  AI-Intent: bugfix/race-condition           │
│  AI-Context: Fixed reconnect timer...       │
└──────────────────┬──────────────────────────┘
                   │ lorekeep history
                   ▼
┌─────────────────────────────────────────────┐
│  Downstream AI reads trailers               │
│  npx lorekeep history --json               │
└─────────────────────────────────────────────┘

Commands

# Install hook (default command)
npx lorekeep
npx lorekeep init

# Query AI commit history
npx lorekeep history
npx lorekeep history --summary
npx lorekeep history --json
npx lorekeep history --file src/ws.ts
npx lorekeep history --tool claude-code
npx lorekeep history --since "2 weeks"

# Write rich context before a commit
npx lorekeep context --tool claude-code --model claude-sonnet-4-6 \
  --intent "bugfix/race-condition" --confidence high \
  --context "Fixed reconnect timer not resetting"

# Session transcript commands (requires Claude Code hooks — see below)
npx lorekeep session list              # list all stored sessions
npx lorekeep session show <id>         # print raw JSONL transcript
npx lorekeep session show <id> --turns # print turn-by-turn summary

# Remove the hook
npx lorekeep uninstall

What Gets Detected

| Tool | Detection Method | |---|---| | Claude Code | CLAUDECODE=1 env var | | Cursor | CURSOR_AGENT=1 env var | | Aider | (aider) in committer name | | Copilot Agent | copilot in author name | | Any tool | GIT_AI_TOOL env var | | Fallback | Co-Authored-By patterns |

Trailer Format

Uses standard git trailers:

AI-Tool: claude-code
AI-Model: claude-sonnet-4-6
AI-Intent: bugfix/race-condition
AI-Confidence: high
AI-Session: mm9kcmf6pmr1
AI-Channel: https://discord.com/channels/123456789/765320407594958868
AI-Files-Rationale: src/ws.ts:fixed-reset | test/ws.test.ts:regression
AI-Context: The retry logic wasn't resetting the backoff timer after a
 successful connection, causing exponential delays to persist across
 reconnects. Added reset() call in onOpen handler.

| Trailer | Source | Description | |---|---|---| | AI-Tool | auto-detected | Tool name (claude-code, cursor, aider, etc.) | | AI-Model | CLAUDE_MODEL / MODEL env | Model that made the change | | AI-Session | temp file / LOREKEEP_SESSION_ID | Per-boot ID grouping related commits | | AI-Channel | DISCORD_CHANNEL_ID / CHANNEL_IDS + optional DISCORD_GUILD_ID | Where the task was requested | | AI-Intent | explicit via lorekeep context | Change category (not auto-extracted) | | AI-Confidence | explicit via lorekeep context | high / medium / low | | AI-Context | explicit via lorekeep context | Reasoning beyond the commit message | | AI-Files-Rationale | explicit via lorekeep context | Per-file rationale |

You can also query trailers with raw git:

git log -1 --format='%(trailers:key=AI-Context,valueonly)' HEAD
git log --grep='AI-Tool:' --format='%h %s'

Session Capture

Beyond commit-level trailers, lorekeep can capture full JSONL session transcripts and store them on a shadow git branch (lorekeep/sessions/v1). The AI-Session trailer in each commit links to the stored transcript — so downstream AIs can read the full reasoning context, not just a summary.

AI-Session: <session-id>
  │
  └─► git show lorekeep/sessions/v1:<session-id>.jsonl

How to enable

npx lorekeep   # or: npx lorekeep

lorekeep init does both steps automatically:

1. Installs the prepare-commit-msg git hook
2. Writes portable Claude Code hooks to .claude/settings.json using npx lorekeep hook <name> — no absolute paths, safe to commit and share across machines

What gets stored

| Event | Action | |---|---| | SessionStart | Records Claude's session ID to /tmp/lorekeep-session-id — stamps every commit in this session | | Stop | Checkpoints the full JSONL transcript to lorekeep/sessions/v1 after each assistant turn | | SessionEnd | Final store of the complete transcript |

Transcripts live on a separate git branch and never appear in git log — they don't pollute the main history.

Retrieving a session

# Via lorekeep CLI
npx lorekeep session list
npx lorekeep session show <session-id>
npx lorekeep session show <session-id> --turns

# Via raw git
git show lorekeep/sessions/v1:<session-id>.jsonl

The shadow branch can be pushed alongside your regular branches so the session history is shared with the team:

git push origin lorekeep/sessions/v1

Tool-Specific Hook Configs

Claude Code (.claude/settings.json)

The included config fires a hook before Claude runs git commit, writing context to .git/ai-context.json. The session hooks (above) are also included for full session capture.

GitHub Copilot Agent (.github/hooks/hooks.json)

The included config does the same for Copilot's coding agent.

Custom / Other Tools

Set environment variables before committing:

export GIT_AI_TOOL="my-custom-tool"
export GIT_AI_CONTEXT="Refactored auth module to use JWT"
git commit -m "refactor: switch to JWT auth"

Project Structure

├── bin/
│   └── lorekeep.js          # CLI entry point
├── src/
│   ├── hook.js              # Hook source (inlined into .git/hooks)
│   ├── install.js           # Init/uninstall logic
│   ├── history.js           # Query AI commits from history
│   ├── context.js           # Write .git/ai-context.json
│   ├── session-store.js     # Git branch storage for session transcripts
│   ├── session.js           # `lorekeep session` CLI handler
│   ├── ai-context.schema.json
│   └── hooks/
│       ├── claude-pre-commit.js   # PreToolUse: capture context before git commit
│       ├── claude-session.js      # SessionStart/Stop/SessionEnd: store transcripts
│       └── copilot-pre-commit.js
├── .claude/settings.json
├── .github/hooks/hooks.json
├── package.json
└── README.md

How lorekeep compares to Entire CLI

Entire CLI is a similar tool that captures AI sessions and links them to code changes. Both tools solve the "why did this code change?" problem — here's how they differ:

| | lorekeep | Entire CLI | |---|---|---| | Metadata location | Git trailers on the commit itself — visible with plain git log | Separate checkpoint branch | | Session storage | Shadow git branch (lorekeep/sessions/v1) — no external service | Separate branch + cloud dashboard | | Infrastructure | Zero — pure git, no account needed | Account + cloud platform | | Recovery/rewind | Not a goal — focused on provenance and audit | entire rewind to restore checkpoints | | Agent support | Claude Code, Copilot, Cursor, Aider, custom (GIT_AI_TOOL) | Claude Code, Gemini CLI, OpenCode, Cursor | | Secret redaction | No | Yes, automatic | | Query | lorekeep history or raw git log --grep='AI-Tool:' | Cloud-based search |

lorekeep is designed to be zero-infrastructure: metadata lives in git itself, queryable with standard git commands, and the hook works even after uninstalling the tool. Entire is a richer platform with recovery features and a cloud layer.

FAQ

Q: What if an AI tool skips hooks (--no-verify)? A: Aider does this by default. Set AIDER_GIT_COMMIT_VERIFY=true to enable hooks. You can also detect aider post-hoc via (aider) in author name.

Q: What if multiple AI tools contribute to one commit? A: The hook detects all tools it can see in the environment and lists them: AI-Tool: claude-code, cursor. The context command also merges context from multiple writers.

Q: Does this modify the commit message the user/AI wrote? A: No — it only appends trailers after the message body. The original message is preserved.

Q: Does the hook need lorekeep installed at commit time? A: No. The hook is self-contained Node.js written directly into .git/hooks/. It works even if you later remove lorekeep — all it needs is node on PATH.