repro-git-hook

Automating Reproducibility and Audit Trails for AI-Assisted Workflows.

---

The Problem

AI coding assistants are transforming scientific computing and regulated software development. However, while version control systems like Git record what code changed, the reasoning, prompts, and contextual decisions behind those changes evaporate the moment the chat window closes.

For work that demands rigorous reproducibility (e.g., peer-reviewed science, financial modeling, healthcare) or strict auditing, leaving no trace of the AI's involvement is a critical vulnerability. Currently, there are virtually no robust tools to automatically capture this context and bind it permanently to the codebase.

The Solution

repro-git-hook is a zero-friction tool that automatically generates a human-readable audit trail of your AI workflows at the exact moment you commit your code.

By hooking directly into the Git lifecycle via pre-commit, it bridges the gap between your code and your AI assistant. It captures environment snapshots, logs the conversation transcript, and statically checks your code for common reproducibility pitfalls—without ever interrupting your flow.

Why "Out-of-Band" Logging?

Some existing approaches try to force the LLM to write logs itself by calling tools (so-called "In-band" logging). This is inherently buggy: when an AI is deep in the weeds of a complex problem, it inevitably forgets to call the logging tool, leading to fragmented audit trails.

repro-git-hook uses "Out-of-band" logging. It passively parses the native logs generated by your IDE/Assistant in the background. The AI never has to "remember" to log anything, meaning your audit trails are as complete as your git commit history and the AI's attention remains 100% on solving your coding problem.

---

Features

1. Agent-First Linting

The script scans your codebase for reproducibility and security violations. Instead of blocking your commit and breaking your momentum, it logs these issues as [WARNING] alerts in your audit file. This leaves a roadmap of technical debt that an AI agent can automatically track down and fix later.

2. Reproducibility Checks

• random-seed: Scans Python/R files and flags RNG usage if seeds (e.g., set.seed(), np.random.seed) are missing.
• env-pinned: Warns if requirements.txt or environment.yml contains unpinned dependencies.
• no-hardcoded-paths: Checks string literals for absolute system paths (C:\, /usr/, /home/).
• no-inplace-data-mutation: Flags writes to data/raw directories to prevent accidental raw data mutation.

3. Security Checks

Scans all files for accidental inclusions of secrets before they are immortalized in git history:

• SSH / RSA Private Keys
• GitHub Tokens
• AWS Credentials
• Generic API keys

---

Installation & Usage

Because repro-git-hook is packaged as a standard Python tool, installation is a single command.

Open a terminal inside any Git repository and run:

uvx --from git+https://github.com/ABindoff/repro-git-hook repro-hook install

(This command uses uv to ephemerally download the tool and automatically configure your .git/hooks/pre-commit file. If you don't have uv installed, you can get it via curl -LsSf https://astral.sh/uv/install.sh | sh or pip install uv)

That's it!

Now, every time you run git commit, an audit log will be automatically generated in .repro/logs/ and seamlessly included in your commit without you ever having to think about it again. Note: by default .repro/ will be added to your .gitignore, remove if you wish to track each log with git.

---

Log Format Example

Each commit generates a .repro/logs/YYYY-MM-DDTHHMMSS.md file:

# Session Log: 2026-05-16T103554

**Git hash:** a3f9c12d8e41

## Reproducibility & Security Checks
> [!WARNING]
> **Agent Action Required:** The following issues were detected. They did not block the commit, but should be addressed for reproducibility.
> * 🚨 **no-secrets**: Potential SSH/RSA Private Key detected! (`config/deploy.yml:14`)
> * ⚠️ **no-inplace-data-mutation**: Potential mutation of raw data directory found. (`scripts/process.R:42`)

## Recent AI Interaction Context
```text
Prompt: Can you help me write a function to download the dataset?
Assistant: Sure, here is the function...

Environment Snapshot

• OS: posix
• Python: 3.11.4