chronicle-setup

Chronicle Setup & Configuration

Chronicle attaches AI conversation transcripts to git commits as git notes and/or a rolling log file. It runs automatically via a PostToolUse hook — no action needed for basic usage.

Verify It's Working

After Claude Code makes a commit, check for the note:

git notes show HEAD

Or check the log file (if using CHRONICLE_MODE=log or both):

ls .chronicle/log/

Push Notes to Remote

Git notes don't push by default. Set up the refspec once per repo:

# Push conversation notes
git config --add remote.origin.push "+refs/notes/commits:refs/notes/commits"

# Fetch notes on pull (so teammates see them too)
git config --add remote.origin.fetch "+refs/notes/commits:refs/notes/commits"

# If using full transcripts (CHRONICLE_FULL=true)
git config --add remote.origin.push "+refs/notes/chronicle-full:refs/notes/chronicle-full"

Then notes travel with git push and git pull automatically.

Configuration

Create a .chronicle/config file in the repo root to override defaults:

# Output mode: notes, log, or both (default: notes)
# - notes: attach conversations as git notes
# - log:   append to per-session files in .chronicle/log/
# - both:  do both
CHRONICLE_MODE=notes

# Store raw JSONL transcript alongside the readable summary (default: false)
# WARNING: This stores the ENTIRE unredacted session JSONL in a git note.
# It can be very large (multi-MB) and MAY CONTAIN SENSITIVE DATA (env vars,
# secrets, file contents). Use for debugging or short-lived inspection only.
CHRONICLE_FULL=false

# Maximum summary size in KB (default 20)
CHRONICLE_MAX_SUMMARY_KB=20

# Disable chronicle for this repo
CHRONICLE_ENABLED=true

Or set these as environment variables.

Rolling Log Files

When CHRONICLE_MODE is log or both, chronicle writes per-session log files to .chronicle/log/. Each session gets its own file named YYYY-MM-DD_topic_sessionid.md. Multiple commits in one session append to the same file.

# List session logs
ls .chronicle/log/

# Commit logs as repo assets
git add .chronicle/log/
git commit -m "update conversation logs"

# Search across all sessions
grep -r "auth bug" .chronicle/log/

To keep logs local instead, add .chronicle/ to your .gitignore.

View Notes in Git Log

# Show notes inline with log
git log --show-notes

# Show notes from a specific ref
git log --show-notes=refs/notes/commits

# Search conversations
git log --all --notes --grep="search term"

Troubleshooting

No note on commit: Chronicle only fires when Claude Code runs git commit via the Bash tool. Manual commits from your terminal won't trigger it.

Empty note: The session transcript might not have been written to disk yet. Chronicle retries once after a short delay, but very fast commits might race.

Note too large: Increase CHRONICLE_MAX_SUMMARY_KB or enable CHRONICLE_FULL=true and use the full ref for deep inspection.

Wrong mode: Check your .chronicle/config file for CHRONICLE_MODE. Valid values are notes, log, or both. Invalid values are reported to stderr.

Security & Redaction

Chronicle automatically redacts detected secrets (API keys, connection strings, tokens, sensitive file content excerpts) before writing. However:

• Secrets without recognized patterns may slip through
• CHRONICLE_FULL=true stores raw JSONL with no redaction
• Always review notes and logs before pushing to public repos