# Local History Explorer

> Local-first knowledge system for CodeVetter — the AI desktop code review workbench for agent-generated code.

Canonical: https://codevetter.com/docs/HISTORY-EXPLORER/

CodeVetter's History Explorer is a local, read-only view of indexed Git facts
and persisted structural graph evidence. It helps a developer or local agent
answer what changed, when it changed, how the structure changed, and what
evidence exists for the change. It does not infer intent, runtime impact,
causation, ownership, or quality from commit activity alone.

## Index and playback

Open **Repo Unpacked → Graph**, then select **Index history**. Indexing stores
normalized local facts in CodeVetter's SQLite database and makes the following
surfaces available:

- exact revision playback with a shared SHA cursor;
- release navigation, including tags outside the currently loaded timeline;
- candidate inflection markers derived from bounded churn and structural facts;
- release-interval contributor participation summaries; and
- the local, read-only [MCP surface](https://codevetter.com/docs/architecture/mcp-sidecar/).

The slider identifies revisions by their full Git SHA, not an array position.
When a selected release or contributor revision is outside the visible window,
the explorer loads a bounded window centered on that exact revision. Playback,
scrubbing, releases, landmarks, and contributor revisions therefore remain
synchronized.

To bound initial storage and indexing work, CodeVetter eagerly stores structural
checkpoints for HEAD, the root boundary, and the newest 24 release revisions
rather than every historical tag. Initial and rebuild indexing never constructs
a structural delta for every historical revision merely to enrich candidate
inflections; those candidates start from normalized facts. Older releases
remain selectable from the complete catalog; their exact structural state is
materialized on first use and then cached locally.

## Releases and coverage

A release is an annotated or lightweight Git tag that matches CodeVetter's
release-tag policy. Coincident tags share one revision rail position but remain
separate release facts. Release intervals are ancestry-aware:

- **complete** means the indexed ancestry proves the interval boundary;
- **partial** means shallow history or another bounded condition prevents a
  complete claim; and
- **divergent** means a tag cannot be placed in the indexed ancestry and has no
  exact interval.

Stale indexes remain readable but are labeled stale. Re-index before relying on
new commits, tags, `.mailmap` identity normalization, or changed structural
engine/schema behavior. When HEAD has advanced by a proven fast-forward, the
index rehydrates its local normalized facts and reads only `old_HEAD..HEAD`;
it appends path/contributor facts for those new revisions rather than replacing
the prior facts. A fast-forward appends structural deltas only for new revisions
whose direct parent is in the bounded loaded window. A tag-only change rebuilds
catalog metadata from SQLite without a Git history walk. An exact-current index
returns a no-op result.

Rewrites, changed `.mailmap` identity rules, fact-schema/classification changes,
or incompatible structural-engine/ignore-policy state deliberately rebuild the
affected derived structural data because that set is not safely append-only.
This is a correctness boundary, not a performance failure.

## Candidate inflections

Candidate inflections are deterministic, non-causal observations. The detector
uses indexed change size/file facts with robust thresholds, then enriches a
bounded candidate with persisted structural delta measurements when available.
The UI exposes reasons, caveats, score components, and coverage. A marker can
mean that a change was unusually large or structurally notable; it does **not**
mean the change caused an outcome, was intentional, or was good or bad.

Generated, vendored, binary, merge, shallow-history, missing-structural-delta,
and storage-bound conditions remain visible caveats. Treat a candidate as a lead
for review, then inspect its exact revision, diff, linked evidence, and tests.

## Contributor summaries

Contributor analytics describe observed participation within an explicit
release-cycle-through or exact ancestry interval:

- primary commit counts and changed lines are single-counted;
- co-author participation is counted separately;
- automation is separated from human/unknown identities;
- aliases are normalized through `.mailmap` without returning raw emails;
- visible areas and revision references are bounded; and
- top rows reconcile with an explicit `other` aggregate.

Selecting a contributor highlights only their bounded observed areas and reveals
their bounded exact revisions. This is navigation evidence, not an attribution
system: participation is not ownership, causation, responsibility, or quality.

## Performance and storage

Normal graph opening, release, landmark, contributor, and MCP reads operate
from the local SQLite index; they do not rescan Git history, reconstruct a
graph, or invoke a model. The UI uses latest-request-wins loading, cached
structural states, adjacent revision prefetch, and bounded windows to keep
scrubbing responsive.

Performance claims are machine- and repository-specific. The qualification
suite records index time, storage per normalized fact, release/contributor read
latencies, cached/uncached scrub latency, CPU/RSS, and Git process counts before
setting a platform budget. Until that qualification is published, use the
visible coverage/freshness state rather than treating a timing observed on one
repository as a product guarantee.

The 2026-07-18 bounded real-worktree qualification used 212 indexed revisions,
112 releases, 26 checkpoints, 606 indexed files, 17 contributor facts, and no
qualifying candidate inflections in a debug test profile. Initial bounded
indexing took 67.96 s with one batched history-Git process, 451 MiB process RSS,
and 134.2 MiB SQLite storage (663.8 KiB/revision, 7.9 MiB/contributor; no
per-landmark value is meaningful when there are zero landmarks). Its compressed
checkpoint payloads used 127.7 MiB; one representative incremental structural
refresh was 269.6 ms.

For fully indexed SQLite reads, the 100-sample release catalog was 0.59 ms p50,
0.66 ms p95, and 1.06 ms max; the full-history contributor summary was 139.8 ms
p50, 143.6 ms p95, and 148.2 ms max. Retained-checkpoint reconstruction was
447.5 ms p50, 457.4 ms p95, and 467.0 ms max. An uncached old-revision
materialization was 2.55 s p95/max in this run. The browser scrub gate remains
p95 under 50 ms and max under 120 ms while a background index is active.

These measurements are named-machine evidence, not a universal SLA. Cold index
and first-open materialization are deliberately background/local work; release,
landmark, contributor, and MCP listing paths must stay on the indexed SQLite
state and must not launch Git, reconstruct graphs, or invoke a model.

These backend figures are machine- and repository-specific and are **not** a
frontend slider budget: the frontend keeps selected and adjacent states in its
own revision cache. The benchmark records the cold and uncached paths so they
cannot be mistaken for ordinary warm interaction. Full structural indexing is
not the normal graph-open or slider path.

## Consolidation boundaries

The normalized history schema currently contains eight tables and thirteen
query indexes. The indexes are intentionally limited to repository/status,
revision/time, path, checkpoint, event, and annotation access patterns used by
the local read services; new indexes need a measured query reason.

Release, landmark, and contributor pagination share one opaque-cursor transport
helper, but retain separate versioned payloads and scope validation. This keeps
cursor misuse and stale-index errors explicit rather than hiding distinct query
contracts behind a generic page type.

The older local **Intel** attribution scan remains deliberately separate from
the normalized history reader. Intel needs raw author-email markers and full
commit bodies to classify local tool attribution; the History Explorer does not
persist either of those fields. Reusing History Explorer facts there would
silently weaken Intel classification and break the history privacy boundary.

The MCP extension adds two bounded read-only tools (`history_list_landmarks`
and `history_list_contributors`) and two versioned resource kinds
(`landmark-catalog` and `contributor-summary`) to the existing local surface.
The 2026-07-18 macOS arm64 release build produced a 67.9 MiB unbundled
`codevetter-desktop` executable. Its temporary Cargo release target was
1.7 GiB (7.5 GiB including debug artifacts) and is deliberately removed after
qualification; packaged-app size needs to be compared only against a matching
signed release build, not this temporary compiler directory.

## Troubleshooting and rollback

- **No releases, landmarks, or contributors:** index history first. Legacy
  local databases remain readable but report unavailable normalized data until
  indexed.
- **Stale or partial coverage:** re-index, then inspect the freshness/caveat
  labels. A shallow clone cannot prove missing ancestry.
- **A release is divergent:** inspect the tag and its history separately; do
  not use its contributor interval as an exact range.
- **Slow re-index:** cancel it, keep using the last ready local index, and retry
  when the repository is idle. Cancelling before publication preserves the
  previous ready generation.
- **Unexpected results:** use the exact SHA, release tag, and coverage state in
  a report. Avoid copying local paths, email addresses, or API keys into shared
  diagnostics.

To roll back a local index, use the app's history cleanup/re-index controls or
clear the local CodeVetter data for that repository and index again. This does
not change Git history. MCP access is independent: disable its repository scope
in **Settings → Agent MCP** when local agent access should stop.

## Local-only boundary

History Explorer and its MCP server run on one machine against local Git and
SQLite data. They do not publish a live graph, create a README embed, synchronize
repositories, write Git history, or call a model during ordinary reads. A hosted
or embeddable graph would need separate privacy, freshness, access-control, and
artifact-retention design.
