玄衡科技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

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, branch reviews and test logs through read-only Git operations.

  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

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.