git-conflict-guardian 0.1.1

Surfaces why code changed before you build on top of it

PR Guardian

Know why code changed before you build on top of it.

PR Guardian runs as a git hook and alerts you immediately after git pull when your uncommitted work overlaps with what a teammate just merged — and explains why their change was made using AI.

---

The Problem

Monday 9am   — You start editing auth.py (3 hours of work, not committed)
Monday 11am  — Teammate merges a PR that also changes auth.py
               You do git pull, have no idea auth.py just changed
               You keep coding on top of it
Wednesday    — You raise a PR
               Reviewer says "this conflicts with PR #847 from Monday"
               You now have to rework 2 days of code

The Fix

⚠  PR Guardian  1 overlapping file — read before you continue

  auth.py  ←  PR #847 by @teammate  2h ago  JIRA-1234
      Your changes overlap at lines 44–91
      "Refactored token refresh to be async — any code calling
       refresh_token() synchronously will break."

Guardian catches this right after git pull, while you can still act on it.

---

Installation

pip install git-conflict-guardian

---

Setup

1. Get tokens

Token	Where to get it
GitHub personal access token	github.com → Settings → Developer settings → Tokens (classic) → repo scope
Anthropic API key	console.anthropic.com → API Keys

2. Configure

guardian setup

Enter when prompted:

• GitHub token: ghp_...
• GitHub repo: owner/your-repo (e.g. acme/backend)
• Anthropic API key: sk-ant-...

Using a LiteLLM proxy (company Claude)?

export ANTHROPIC_BASE_URL=https://your-company-litellm-url/

Add to ~/.bashrc or ~/.zshrc to persist.

3. Install the git hook

cd /path/to/your/project
guardian install

4. Done

Use git pull as normal. Guardian fires automatically after every pull.

---

Commands

guardian install          # install post-merge hook into current repo
guardian setup            # configure tokens interactively
guardian run              # manually trigger a check
guardian run --no-ai      # check without AI summary (faster)
guardian run --verbose    # show output even when no overlaps found
guardian blame auth.py --line 67   # explain why a specific line exists

---

How it works

git pull
    ↓
post-merge hook fires
    ↓
Guardian checks:
  - what files changed in this pull?      (git diff HEAD~1..HEAD)
  - what files do YOU have uncommitted?   (git diff)
  - overlap found?
    ↓
Fetches the PR via GitHub API
Calls Claude to generate a plain-English briefing:
  - Why was this change made?
  - What assumption does it invalidate?
  - What should you watch out for?
    ↓
Prints to terminal instantly

---

Difference from git merge conflicts

	git conflict	PR Guardian
When	After merge fails, repo is broken	Before you commit, still coding freely
Info	"there's a conflict"	Why it changed + what breaks
Action	Forced to stop and fix	Choose to fix now or keep going

Guardian catches soft conflicts — same file touched, not yet a hard merge conflict. By the time git pull shows a conflict, you've already wasted hours.

---

Requirements

• Python 3.10+
• Git
• GitHub personal access token (repo scope)
• Anthropic API key (or LiteLLM proxy)