#Usage guide

reposummary summarize <repo> --window <window> --synthesis <backend> extracts a git repository's activity over a time window and renders a Markdown journal, optionally narrated by an LLM. <repo> defaults to the current directory; --window and --synthesis are required and have no default.

#Windows

--window accepts the following forms. An unrecognized window is a hard error, never a silent fallthrough.

The tip of the window is --branch (default HEAD).

#Synthesis backends

--synthesis selects the prose backend explicitly. There is no silent fallback: the chosen backend must work, or the command errors. reposummary never quietly downgrades one backend to another.

--model selects the model id (default haiku). Both short aliases (e.g. haiku) and full model ids (e.g. claude-haiku-4-5-20251001) are passed through to the backend verbatim — the Anthropic API and the claude CLI both accept alias ids. The model is only consulted when the backend is claude-cli or anthropic-api.

#Caching and incremental efficiency

A journal for a fixed (firstSHA, lastSHA, synthesis, model, version, windowLabel) tuple is deterministic, so identical windows reuse cached output. The cache key is a sha256 over those six inputs:

• firstSHA and lastSHA — the commit range actually covered by the window
• synthesis — the selected backend
• model — the model id
• version — the reposummary version (so a new release never serves stale prose)
• windowLabel — the resolved window heading, so that two windows with no

commits (both SHAs empty) never collapse to the same entry and serve a cached journal under the wrong heading

Entries are plain Markdown files under the cache directory ($XDG_CACHE_HOME/reposummary, or ~/.cache/reposummary). Two window expressions that resolve to the same commit range and produce the same label share a cache entry, so repeated summaries cost O(new commits), not O(window size).

The cache is self-maintaining: each successful write opportunistically prunes entries whose files have not been read in the last 90 days, and every cache hit refreshes the entry's timestamp so frequently-used journals never age out. Pruning is best-effort — a failed prune never fails the write.

• --no-cache disables the cache entirely (always recompute, never read or write).
• --cache-dir <path> overrides the cache directory.

#Examples

# Deterministic journal for today, printed to stdout
reposummary summarize . --window today --synthesis none

# Last week, narrated via the Anthropic API
ANTHROPIC_API_KEY=... reposummary summarize ~/code/myproj --window week --synthesis anthropic-api

# A fixed one-month span from a date, no LLM
reposummary summarize . --window 2026-06-11+1month --synthesis none

# A release range, narrated via the local claude CLI, written to a file
reposummary summarize . --window v0.1.0..HEAD --synthesis claude-cli --output CHANGES.md

# The whole history, ignoring any cached output
reposummary summarize . --window all --synthesis none --no-cache