玄衡科技XUANHENG TECHNOLOGY
MENU

PROJECT 03 · OPEN SOURCE · GIT EVIDENCE

Snapshot Runner

Deterministic, read-only Git evidence for coding agents and automation.

Status: Open Source

GitHub

FOCUS

  • Git Evidence
  • Read-only Collection
  • Agent Tooling
A real terminal capture: snapshot-runner repo-status prints the snapshot id, the artifact paths, the security boundary and the manual review workflow.
A real repo-status run on a disposable example repository — output shown verbatim.

01 · Overview

Overview

Snapshot Runner collects repository state, changes, branch history and existing test logs into local artifacts. It never modifies the inspected repository, runs tests, calls a model, commits or pushes, and requires no API key.

Four collection commands publish deterministic, hash-verified snapshots with bounded summaries, and a targeted evidence reader returns just the relevant part of an existing snapshot, so an agent reviews the evidence it needs instead of whole repositories.

Captured content stays untrusted evidence rather than agent instructions; refusals and explicit evidence gaps keep safety boundaries visible in every artifact.

02 · Capabilities

Capabilities

  1. 01

    Repository Evidence

    Collecting branch state, diffs, untracked files and branch reviews through read-only Git operations, and existing test logs within explicit size limits.

  2. 02

    Deterministic Artifacts

    Atomically publishing hash-addressed snapshots with controlled file modes and re-verifiable size and SHA-256 metadata.

  3. 03

    Targeted Reading

    Reading a single file or field from an existing snapshot without re-running Git.

  4. 04

    Fail-closed Boundaries

    Rejecting traversal, symlinks, special files and unsupported capabilities instead of running repository-controlled programs.

03 · Workflow

Workflow

  1. 01

    Collect Read-only Evidence

  2. 02

    Publish Deterministic Snapshot

  3. 03

    Review Bounded Summary

  4. 04

    Read Targeted Evidence

04 · System View

System View

  1. 01

    Command & Contract Layer

  2. 02

    Read-only Git Collection Layer

  3. 03

    Snapshot Artifact Layer

  4. 04

    Summary & Evidence Reader Layer

System diagram: four stages — collect read-only evidence, publish deterministic snapshot, review bounded summary, read targeted evidence — above the private snapshot store, the trust boundary and the four layers.
The evidence path, the private store and the boundary; as of September 2026.

05 · Current State

Current State

Implemented

Release 2.3.0 on PyPI provides the four collection commands and the targeted reader, snapshot and summary contracts, and a standard-library Python CLI verified on Ubuntu 24.04.

Current Focus

Keeping the public CLI contract and evidence schemas stable, recorded in tool_cli_contract.json.

Next Direction

Extending deterministic evidence coverage for further repository states while preserving read-only, fail-closed guarantees.

06 · Principles

Principles

  1. 01

    Captured repository content is untrusted evidence, not agent instructions.

  2. 02

    The tool never modifies the repository, runs tests, calls a model, commits or pushes.

  3. 03

    Refusals and evidence gaps stay explicit; automatic analysis is intentionally unavailable.