Starktrace

Starktrace is a local-first Git intelligence dashboard for understanding how work entered the current branch, where change pressure is accumulating, how repository areas are evolving, and where historical knowledge is concentrated. It reads local Git objects and never uploads repository data.

Run it

Requirements: Node.js 22 or newer and Git available on your PATH.

npx @starkprince/starktrace

Run the command anywhere inside a Git working tree. Starktrace resolves the repository root, indexes commits reachable from the current HEAD, starts a loopback-only server at http://localhost:2908, and opens the dashboard. Press Ctrl+C to stop it.

Usage: starktrace [options]

Options:
  --port <number>  Use a port other than 2908
  --no-open        Start without opening a browser
  --no-cache       Do not read or write the local analysis cache
  -h, --help       Show help
  -v, --version    Show the installed version

If the selected port is occupied, Starktrace exits instead of silently choosing another one.

What it shows

• Overview: the current branch's first-parent delivery trace, leading hotspots, integration signals, and latest reachable release.
• Merges: delivered files and areas, corrective follow-ups, and exact on-demand ancestry, contributors, development span, overlap, and line impact.
• Risk: explainable file attention, temporal coupling, and source/test pairing.
• Evolution: reachable tags, release payloads, repository-area lifecycle, and sustained rename migrations.
• People: historical knowledge concentration and sustained ownership transitions.
• History: filtered commit evidence without treating activity volume as performance.

Weekly, monthly, quarterly, yearly, and all-history ranges roll backward from the newest reachable commit, so archived repositories remain useful. Quarterly is the default.

Progressive local analysis

Starktrace opens after a fast topology pass. File history, merge/status evidence, and rename enrichment arrive progressively without blocking the server. Refresh stages a complete replacement in memory; if it fails, the previous dashboard remains visible.

Completed schema-v3 analysis is cached outside the repository and invalidated when HEAD, tags, .mailmap, shallow state, or the analyzer version changes:

• Windows: %LOCALAPPDATA%\starktrace\Cache
• macOS: ~/Library/Caches/starktrace
• Linux: $XDG_CACHE_HOME/starktrace or ~/.cache/starktrace

The cache is gzip-compressed, user-local, capped at 500 MiB, and replaceable. Use --no-cache for a memory-only run. Starktrace never writes inside the analyzed repository.

Interpretation limits

Starktrace distinguishes exact Git facts from heuristics:

• Merge parents, first-parent diffs, reachable commits, tags, file paths, authors, and .mailmap identities are Git facts.
• Corrective intent, stability, knowledge concentration, source/test pairing, migrations, and ownership transitions are evidence-based heuristics and are labeled as such.
• Local Git cannot reliably recover deleted branch names, code-review duration, approvals, CI results, deployments, or historical merge conflicts.
• Source/test pairing describes files changed together; it is not test coverage.
• Contributor and ownership views are context maps, never productivity or replaceability scores.

No runtime assets, analytics, or telemetry are fetched from the network. A remote URL may be displayed as an explicit commit link, but Starktrace never opens or requests it automatically.

Local API

The loopback server exposes schema-v3 endpoints used by the packaged dashboard:

• GET /api/progress
• GET /api/insights?range=week|month|quarter|year|all
• GET /api/commits with cursor, range, contributor, type, and search filters
• GET /api/merges/:hash
• POST /api/refresh

There is no CORS exposure, background watcher, remote service, or directory listing.

Development

npm install --ignore-scripts
npm run vendor
npm run check
node ./bin/starktrace.mjs --no-open --no-cache

npm run vendor copies pinned Chart.js and font assets into the published UI and records their license texts. npm pack runs the same asset and quality checks before creating a tarball.

License

Starktrace is available under the MIT License. Bundled browser assets retain their own licenses; see THIRD_PARTY_NOTICES.md.