Refscope

An observatory for Git refs and history. Local, read-only, allowlist-scoped.

Refscope watches one Git repository and records what changes — force pushes, rebases, resets, ref movements, commit arrivals — while keeping observed facts separate from any interpretation. It runs entirely on your machine, does not write to the repository, and does not invoke external GPG.

Landing page: https://simota.github.io/refscope/

Repository layout

• apps/cli/: refscope CLI — npx -y github:simota/refscope serves the API and the bundled UI on one port. Distributed from this repository, not from the npm registry.
• apps/api/: read-only Git inspection API (Node.js 22 ESM, no framework).
• apps/ui/: React + Vite UI. Bundled into the CLI at publish time; developed against the live API in this repository.
• apps/web/: Astro landing page deployed to GitHub Pages.
• docs/brand/: brand guidelines, design tokens, voice and tone, microcopy, and the LP specification.
• docs/spec-v0.md: product and architecture specification.

Prerequisites

• Node.js 22 or newer.
• Corepack enabled, or pnpm 10.9.0 available on PATH.

This repository uses pnpm workspaces from the root. Keep a single root pnpm-lock.yaml committed when dependencies are installed or changed.

Run without installing

Refscope is run directly from this GitHub repository. There is no npm package to install and nothing to clone by hand — Node.js 22 is the only prerequisite.

cd /path/to/your/repo
npx -y github:simota/refscope

Refscope opens at http://127.0.0.1:4175 and observes the current working directory. To watch a different repository:

npx -y github:simota/refscope --repo /absolute/path/to/another/repo

Pin a tag if you want a specific revision: npx -y github:simota/refscope#v0.0.1. Without a tag, npx follows the default branch.

Full options and the CLI security model are in apps/cli/README.md.

What you see in the UI

• Twelve stable lenses over the same repository. Each lens is a different way to read the same observed facts. Refs, filters, and the selected commit are shared across lenses — switching is local.
  • Timeline lenses — Live (the commit timeline as a single calm column), Pulse (a canvas of file-change particles that burst when a file changes), Stream (one row per file change in reverse chronological order).
  • Risk lenses — Hotspot (LOC × churn scatter for refactor ROI), Risk Trend (riskScore over time with brush-to-zoom), Risk Heatmap (author × date or date × hour intensity), Co-change (force-directed graph of files that move together), Drift (local branches plotted by ahead/behind and staleness), Outbox (uncommitted / stashed / ahead-of-upstream in three columns).
  • Specialist lenses — Digest (24h / 7d activity summary across contributors, hotspots, risky commits, and ref activity), Rescue (history-rewritten snapshots with copyable git reflog / branch-recovery commands), Symbol (per-symbol history when a file is opened from a code location).
• Feature-flagged Ref Incident Flight Recorder (?flight=1 or VITE_REFSCOPE_FLIGHT_RECORDER=1) — a read-only incident timeline for observed ref movements. It separates observed facts (ref, previous hash, current hash, observed time, detection source) from derived explanations, and provides copyable incident notes plus investigation commands. The recorder is memory-only on the server and only covers events observed while Refscope is running.
• Fleet mode (?fleet=1) — a multi-repository overview that polls allowlisted repositories at 30s intervals, aggregates activity across a 1h / 6h / 24h / 7d window, and surfaces per-repo SSE availability and untracked exclusions. Click a row to switch into Detail mode for that repository.
• Working-tree changes are surfaced as a first-class entry alongside committed history, and uncommitted edits feed into the Pulse, Stream, and Outbox lenses too.
• File history with co-change — right-click any file row to open its history view, complete with a hunk timeline, branch-drift halo, and a related-files (co-change) panel.
• Period summary — labelled metric bars for commit count, additions, deletions, signed commits, merge commits, and live-update arrivals across a chosen window.

The sections below are for working on Refscope itself — the API, the UI, the CLI, and the landing page.

Building from source

Setup

corepack enable
pnpm install

Development

Start the API and UI for this repository with one command:

make dev-self

Open the UI at http://127.0.0.1:5173.

To inspect another Git repository, pass an allowlisted repository path:

make dev-app RTGV_REPOS=viewer=/absolute/path/to/git/repo

make dev-self, make dev-app, and make dev-api validate the repository path before starting services. If the path is missing, relative, does not exist, or is not the Git root containing .git, the terminal explains what to fix.

Equivalent explicit two-terminal setup:

RTGV_REPOS=viewer=/absolute/path/to/git/repo pnpm dev:api
VITE_RTGV_API_BASE_URL=http://127.0.0.1:4175 pnpm dev:ui

The API listens on http://127.0.0.1:4175 by default.

The web UI reads the API at http://127.0.0.1:4175 by default. Override it when the API runs elsewhere:

VITE_RTGV_API_BASE_URL=http://127.0.0.1:4175 pnpm dev:ui

When multiple repositories are allowlisted, the web UI repository selector switches the active API repository and reloads refs, commits, details, diffs, and SSE updates for that repository. The top-bar ref selector and sidebar can switch the commit timeline between HEAD, API-provided local branches, remote-tracking branches, and tags. Ref selections are sent to the API as full ref names where available, so a branch and tag with the same short name do not collide. If the currently selected ref disappears during realtime polling, the UI reloads the ref list and falls back to HEAD or another remaining ref. Annotated tags are reported with their peeled target commit hash instead of the tag object hash, keeping branch, remote, and tag refs aligned for commit-history display. The Command+K / Ctrl+K command palette uses the same API-provided refs and selected commit state for ref switching, current-hash copy, and clearing active timeline filters.

Allowlist format:

RTGV_REPOS=repoId=/absolute/path,otherRepo=/absolute/path

Only repoId values from RTGV_REPOS are accepted by API routes. Each allowlisted path must resolve to a Git working tree root containing a .git directory or file, and each repoId must be unique. Clients never provide raw repository paths.

Realtime SSE polling interval can be adjusted when needed:

RTGV_REF_POLL_MS=1000 RTGV_REPOS=viewer=/absolute/path/to/git/repo pnpm dev:api

Numeric runtime settings such as PORT, RTGV_GIT_TIMEOUT_MS, RTGV_DIFF_MAX_BYTES, and RTGV_REF_POLL_MS must be decimal positive integer strings. Values using numeric coercion syntax such as 1e3 or 10.5 are rejected at startup. RTGV_GIT_TIMEOUT_MS and RTGV_REF_POLL_MS must also fit Node.js timer bounds (1 through 2147483647). RTGV_DIFF_MAX_BYTES defaults to 4000000 (4 MB) and is capped at 16777216 bytes so Git output remains bounded.

When overriding browser origins for CORS, provide comma-separated HTTP(S) origins only, or set the whole value to * for local unrestricted access:

RTGV_ALLOWED_ORIGINS=http://localhost:5173,https://viewer.example.test

Origins with paths, queries, fragments, credentials, or non-HTTP schemes are rejected during API startup.

Build

Build the API and the UI from the repository root:

pnpm build

Build a specific package:

pnpm build:api          # syntax-check the API
pnpm build:ui           # build the UI
pnpm build:cli          # bundle the CLI (apps/api/src + apps/ui/dist into apps/cli/)
pnpm --filter @realtime-git-viewer/web build   # build the landing page

Working with the CLI source

Build and run the unpublished CLI without npm publishing:

pnpm --filter refscope build
node apps/cli/bin/refscope.mjs --repo "$(pwd)" --no-open

pnpm --filter refscope build copies apps/api/src/*.js into apps/cli/src/bundled-api/ and builds the UI with VITE_RTGV_API_BASE_URL="" into apps/cli/src/static/. The same script runs as prepublishOnly, so the published tarball is self-contained and has no workspace dependencies.

Working with the landing page

pnpm --filter @realtime-git-viewer/web dev      # local preview at 127.0.0.1:4321
pnpm --filter @realtime-git-viewer/web build    # produce dist/
pnpm capture:web                                # regenerate captured screenshots and OGP card

The captured media in apps/web/public/media/ is committed; the capture script is for refreshing it after meaningful UI changes. GitHub Pages deployment is automated by .github/workflows/pages.yml on push to main.

API

Read-only endpoints (none of them write to a repository):

• GET /health
• GET /api/repos
• GET /api/repos/:repoId/refs
• GET /api/repos/:repoId/refs/drift
• GET /api/repos/:repoId/branches/grouped?prefix=feat/
• GET /api/repos/:repoId/stashes, /worktrees, /submodules, /state, /worktree
• GET /api/repos/:repoId/commits?ref=HEAD&limit=50&search=message&author=name&path=src/app.ts (mode=pickaxe|regex|message&pattern=... selects the other search modes)
• GET /api/repos/:repoId/commits/summary?since=...&until=...&groupBy=prefix
• GET /api/repos/:repoId/commits/:hash
• GET /api/repos/:repoId/commits/:hash/diff
• GET /api/repos/:repoId/commits/:hash/risk
• GET /api/repos/:repoId/commits/:hash/refs
• GET /api/repos/:repoId/compare?base=main&target=feature/refscope
• GET /api/repos/:repoId/compare/cherry?base=main&target=feature/refscope
• GET /api/repos/:repoId/files/history?path=...
• GET /api/repos/:repoId/files/range-history?path=...&lineStart=1&lineEnd=20
• GET /api/repos/:repoId/files/related?path=...
• GET /api/repos/:repoId/files/hotspot?ref=HEAD&limit=500&commitCap=200
• GET /api/repos/:repoId/symbols/history?path=...&funcname=...
• GET /api/repos/:repoId/events
• GET /api/repos/:repoId/ref-flight/events?limit=100
• GET /api/fleet/snapshot?window=24h&include=repoA,repoB

Allowlist management (see the Origin rules under "Security constraints"):

• POST /api/repos with { "id": "...", "path": "/absolute/path" }
• DELETE /api/repos/:repoId (UI-added repositories only)

Merge commits are summarized and diffed against their first parent.

Commit detail responses include metadata, refs, and a bounded changed-file summary derived from read-only git show --numstat and git show --name-status commands. Full patch text remains available through the separate diff endpoint. For renamed files, the summary attaches additions and deletions to the destination path reported by --name-status. File statistics use Git's NUL-delimited output, preserving literal file names containing tabs, newlines, trailing spaces, or => without treating them as record separators or rename notation. Commit lists, details, comparisons, period summaries, risk inputs, working-tree totals, and live commit events use the same numstat parser. The :hash path parameter for commit detail and diff endpoints must be a full 40-character hexadecimal commit object ID; abbreviated hashes are rejected before Git execution to avoid ambiguous object resolution. Full object IDs are also checked with git cat-file -t before detail or diff reads, and non-commit objects are rejected without returning their contents. Commit list and detail responses include signed and signatureStatus fields, but cryptographic signature verification is intentionally not performed by the API because Git can invoke repository-configured GPG programs for signed commits. Until offline signature parsing is implemented, signed commits are reported as signed: false with signatureStatus: "unknown". Commit list responses include bounded git log --numstat aggregate metadata as added, deleted, and fileCount, which the timeline uses before loading full commit details. The optional commit-list search parameter is a bounded, case-insensitive, literal search over commit messages. The optional author parameter is a bounded, case-insensitive literal match against commit authors. Both filters escape Git regex metacharacters independently so combining them keeps literal matching semantics. The optional path parameter filters commits to a repository-relative file or directory path and rejects malformed components such as empty segments, ., and ... The optional commit-list ref parameter must resolve to a commit before the history read runs; the API then reads history from the resolved commit object ID. Missing refs and non-commit object IDs return a public 404 error. The optional limit parameter must be a decimal positive integer; accepted values are clamped to the API maximum of 200 commits and invalid values return a public 400 error. Commit-list query parameters are scalar: duplicate ref, limit, search, , or parameters return a public error instead of being silently collapsed to one value. Compare responses summarize with ahead/behind counts, changed-file totals, added/deleted line totals, merge-base information when available, and copyable local Git commands for , , and . The copyable commands keep and as separate revision tokens, while the backend comparison commands read from the resolved commit object IDs. Both compare revisions must resolve to commits before any comparison command runs. When message, author, or path filters are active and the API returns no commits, the web UI shows a filter-specific empty state so a zero-result search is distinguishable from an unfiltered empty ref.

The SSE endpoint keeps an in-memory ref snapshot per connection, polls the allowlisted repository refs, and emits typed events:

• connected
• ref_created
• ref_updated
• ref_deleted
• commit_added
• history_rewritten
• error

The web UI uses history_rewritten events for the realtime notice and the sidebar alert list. The alert list is event-driven and starts empty; it does not show synthetic rewrite warnings before the API observes one. Rewrite alerts show observed facts (ref, previous hash, current hash, observed time, and detection source) separately from the interpretation, and include a copyable incident note for team coordination. When the Flight Recorder flag is enabled, the UI also exposes the in-memory ref-flight event log as an incident timeline with the same observed/derived separation. It is read-only, allowlist-scoped, and does not persist server-side state; restarting the API clears the server-side flight log. The web UI also marks commits observed through real commit_added SSE events as new in the timeline after the refreshed commit list includes those hashes. The highlight state is local to the current browser session and clears when switching repositories. Live updates can be paused from the top bar or command palette. While paused, incoming SSE events are counted and announced through a polite live region, but the timeline is not refreshed until updates are resumed. The timeline includes a read-only compare bar for pinning a base ref/commit and target ref, preserving selected commits across ref switches when possible, and copying local Git comparison commands. The timeline also includes a commit activity overview with labeled metrics and mini bars for commit count, additions, deletions, signed commits, merge commits, and live-update new commits. If the SSE stream emits a typed error event, the web UI surfaces the sanitized API error message in the timeline instead of silently dropping the event.

Security constraints

• Repository access is allowlist-only through RTGV_REPOS.
• Duplicate repoId values in RTGV_REPOS are rejected at startup instead of being silently overwritten.
• Allowlisted repository paths must be absolute Git working tree roots, not arbitrary directories or repository subdirectories.
• The shared Git runner also rejects non-absolute, non-canonical, and non-Git working tree root paths before spawning Git, so future internal call sites cannot accidentally read directories outside the configured allowlist model.
• Malformed percent-encoded API paths are rejected as public 400 errors before repository lookup.
• Git commands are executed with argument arrays and shell: false.
• Git command execution is limited to the read-only command set used by the API (cat-file, cherry, config (read-only lookup), diff, for-each-ref, log, ls-files, merge-base, rev-list, rev-parse, show, and the stash list / submodule status / worktree list subcommands).
• Git command arguments must start with a command name. Leading Git global options such as -c, --git-dir, --work-tree, and --namespace are rejected before spawn so internal call sites cannot override the hardened execution context.
• Git command execution rejects output-file options such as --output before spawn, so read-only API call sites cannot accidentally write diff output to arbitrary filesystem paths.
• Git command execution rejects --no-index diff mode before spawn, so diff reads stay scoped to the allowlisted repository working tree.
• Git command execution strips inherited GIT_* environment variables before setting safe runtime overrides, so variables such as GIT_DIR cannot redirect reads away from the allowlisted repository path.
• Git command execution starts Git with --no-pager, rejects explicit pager options, and overrides inherited pager environment with cat, so API reads do not invoke user-configured pagers.
• Git command execution ignores user-global and system Git configuration by setting GIT_CONFIG_GLOBAL to the null device and GIT_CONFIG_NOSYSTEM=1; repository-local configuration is still read, with unsafe behaviors disabled by explicit command flags where needed.