# Agent Integration Guide

GitScope works with any AI agent that can run shell commands.

## Quick setup

```bash
pip install gitscope
```

Add one instruction to your agent's system prompt or config:

```
Before reviewing any diff, run: gitscope review <base>..HEAD
```

That's it. GitScope is silent (exit 0) when nothing is noteworthy, so it won't add noise.

## How it works

```bash
# Analyze last commit
gitscope review HEAD~1..HEAD

# Analyze a PR branch
gitscope review main..feature-branch

# JSON output for programmatic use
gitscope review main..HEAD --format json
```

### Exit codes

| Code | Meaning | Agent action |
|------|---------|--------------|
| 0 | No high-signal findings | Continue normally |
| 1 | Findings present | Read stdout, address each finding |
| 2 | Error (not a repo, bad ref) | Report the error |

### Example output (text)

```
⚠ GitScope: 2 changes need review

1. SIGNATURE CHANGED: create_user(name, email) → create_user(name, email, role="viewer")
   File: src/auth/users.py:34
   Impact: Backward-compatible (new kwarg has default)
   Callers: api.py (2 calls), admin.py (1 call)

2. SYMBOL REMOVED: `legacy_auth`
   File: src/auth/compat.py:12
   Impact: 3 callers will break:
     middleware.py:45  `legacy_auth(request)`
   Review: Ensure no remaining callers depend on this symbol
```

### Example output (JSON)

```json
{
  "version": "0.1.0",
  "ref_range": "main..HEAD",
  "findings": [
    {
      "category": "SIGNATURE_CHANGED",
      "symbol": "create_user",
      "file": "src/auth/users.py",
      "line": 34,
      "before_signature": "def create_user(name, email)",
      "after_signature": "def create_user(name, email, role=\"viewer\")",
      "impact": {
        "production_callers": 3,
        "test_callers": 2,
        "callers": [...]
      },
      "review_hint": "Review the signature change for compatibility"
    }
  ],
  "stats": {
    "files_analyzed": 5,
    "symbols_changed": 8,
    "silence_reason": null
  }
}
```

## Integration patterns

### CI/CD pre-review

```bash
# In your CI pipeline, before AI review
FINDINGS=$(gitscope review $BASE_SHA..HEAD --format json)
if [ $? -eq 1 ]; then
  echo "$FINDINGS" | your-agent-review-command
fi
```

### Git hook

```bash
# .git/hooks/post-commit
gitscope review HEAD~1..HEAD
```

## Supported languages

Python, TypeScript/JavaScript, Go. More coming soon.
