GitPin

[!IMPORTANT] Archived 2026-10-15. Superseded by Assay, a reference architecture for deterministic agent control. Why: the same agent writes both the change and its evidence manifest, so the gate proves coverage and hash pinning, not that a claim is true. Assay moves the decision into deterministic code instead. The last release, 0.6.4, stays on npm. The rest of this README is unchanged.

Why it exists

Coding agents now open pull requests with confident descriptions: "added retry logging", "updated the protocol doc", "no other files touched". A reviewer who wants to trust one of those sentences has to open the file and hunt for the line, then do it again for the next sentence. Most reviewers stop checking, and an agent can change a file it never mentions.

GitPin turns the description into evidence. The agent commits a small manifest in which every material claim names the paths it covers and points at an exact line slice with a SHA-256 of its text. A required check compares that manifest with the real diff. Any changed file that no claim covers fails the build, and every claim that passes can be re-checked by a human with git show, without GitPin, without the agent and without a hosted platform.

Quickstart: the gate in 30 seconds

git clone https://github.com/shmindmaster/gitpin.git && cd gitpincorepack enable && pnpm install --frozen-lockfilepnpm demo:gate

demo:gate builds GitPin, creates a throwaway synthetic repository in a temp folder, and runs the real gitpin gate twice. The agent's first commit changes docs/protocol.md without claiming it, so the gate fails with exit 1. The agent adds one evidence locator (line 5, hashed) and the same gate passes with exit 0:

$ gitpin gate --base <base> --head <agent-commit>status: failed   exit code: 1violation: uncovered-change: Changed path has no material claim: docs/protocol.md.covered: synthetic-service/docs/overview.md:3 @ <agent-commit> (verified)$ gitpin gate --base <base> --head <locator-commit>status: ok   exit code: 0covered: synthetic-service/docs/overview.md:3 @ <locator-commit> (verified)covered: synthetic-service/docs/protocol.md:5 @ <locator-commit> (verified)

Nothing is written outside the temp folder, and the folder is removed afterward.

See it run

Watch the 90-second film → · The 30-second cut →

Use it in your repo

1. Install the trusted policy on your default branch (a separate, reviewed change, so a pull request can never weaken its own gate):

mkdir -p .gitpincurl -fsSL https://raw.githubusercontent.com/shmindmaster/gitpin/v0.6.4/templates/gate.yml -o .gitpin/gate.yml

2. Make it a required check:

name: Agent delivery assuranceon: pull_request            # never pull_request_targetpermissions:  contents: readjobs:  evidence:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1        with:          fetch-depth: 0          ref: ${{ github.event.pull_request.head.sha }}      - uses: shmindmaster/gitpin@514799cb0eae55e965e51d510d5e7a0a7604c9cc # v0.6.4        with:          base-sha: ${{ github.event.pull_request.base.sha }}          head-sha: ${{ github.event.pull_request.head.sha }}

3. Each agent PR commits .gitpin/change-evidence.json, starting from templates/change-evidence.json. The full setup, including rulesets, is in docs/pr-evidence-gate.md.

Give your agent the evidence tools. The local MCP server lets Claude Code, Codex, Cursor and other MCP clients find candidates and produce the evidence packs the gate checks:

# Run inside any committed Git repositorynpx -y [email protected] init --client codex      # or claude-code, cursor, windsurf, zed, continue

init writes ~/.gitpin/repositories.yaml outside the repository, runs doctor, prints a first evidence line with a full SHA, and prints paste-ready MCP config. It never edits the repository it registers.

How it works

flowchart LR  subgraph BASE["Trusted: base commit"]    POL[".gitpin/gate.yml<br/>policy"]  end  subgraph HEAD["Submitted: head commit"]    MAN[".gitpin/change-evidence.json<br/>claims → path, lines, sha256"]  end  DIFF["git diff merge-base..head<br/>the real change"]  POL --> GATE{"gitpin gate<br/>read-only, never runs PR code"}  MAN --> GATE  DIFF --> GATE  GATE -- "uncovered path, wrong hash,<br/>sensitive path" --> FAIL(["exit 1: check fails"])  GATE -- "every changed path covered,<br/>every slice re-hashed" --> PASS(["exit 0: report with full-SHA citations"])  PASS -.-> HUMAN(["Reviewer: git show &lt;sha&gt;:&lt;path&gt;"])

The gate reads policy only from the trusted base commit and the manifest only from the head commit, through git show, never from a working tree. It compares the merge-base diff, re-hashes every cited line slice, and emits a report whose citations carry full SHAs.

The MCP side follows one loop. Search returns candidates, never answers. Proof turns a candidate into an evidence pack. Verification re-checks it with git show:

pin.search_docs / pin.search_code   candidates only, with a forced next step          → pin.prove               evidence pack: path, line, full SHA, content hash          → pin.verify              independent git show re-check, HEAD match report          → you: git show <sha>:<path>

Resource gitpin://catalog; prompt prove-with-git-head. Cite formats are in docs/cite-spec.md; an agent skill template is in templates/gitpin-skill.md.

Guardrails and non-goals

• Read-only, always. GitPin never writes, commits or pushes to a repository it reads, and the gate never executes pull-request code.
• A PR cannot weaken its own gate. Policy comes from the base commit; evidence comes from the head commit; the dirty working tree is never read.
• Uncommitted work is never evidence. Dirty and untracked content is excluded from HEAD citations.
• Sensitive paths stay sensitive. Deny rules apply to evidence, and the manifest cannot cite itself.
• Candidates are not claims. Search output is labelled evidence-candidates and must go through pin.prove.
• No embeddings, no database, no reindex. Evidence comes from Git objects, so it works offline and on private repositories.

Not goals: semantic search, writing or committing code, replacing GitHub Issues or PR automation, or treating a non-Git folder as one repository.

Status and limits

This source tree and its packed documentation describe GitPin 0.6.4 without asserting publication status. Check each channel independently: npm, the MCP Registry (io.github.shmindmaster/gitpin) and GitHub Releases. Node 20 or later. Site: shmindmaster.github.io/gitpin.

GitPin verifies coverage, location, revision and content hash. It proves what was committed, not that a claim is true: it does not establish semantic correctness, runtime behavior, authorship, authorization or compliance. That judgment stays with the reviewer, who now reads one cited line instead of hunting for it. Planned work is in the roadmap.

Configuration

Default registry: ~/.gitpin/repositories.yaml (legacy compatibility fallback: ~/.repocontext/... if present).

Formerly RepoContext 0.3.x. See migration.

Docs

Tools · PR evidence gate · Clients · Architecture · Compare · FAQ · Troubleshooting · Roadmap · Governance

Contributing, security and license

• Contributing: start with an issue for bugs and proposals, then follow CONTRIBUTING.md. Good first issues are labelled good first issue. Before a pull request: pnpm validate && pnpm build && pnpm verify:package.
• Security: report vulnerabilities privately through a GitHub security advisory, as described in SECURITY.md. Please do not open a public issue.
• License: MIT.

Created and maintained by Sarosh Hussain. Related open source: Assay keeps an agent's decision out of its side effects; CrewScore checks whether an agent's prompt writes its safeguards down.