gitscope 0.1.1

Code intelligence for AI agents — local-first structural analysis of git diffs

GitScope

Catches the structural breaks that pass code review.

The catch

Flask changed redirect()'s default from 302 to 303 (PR #5898). A reviewer sees a one-line diff. GitScope sees 7 callers that silently change behavior:

$ gitscope review eca5fd1d~1..eca5fd1d

⚠ GitScope: 2 changes need review

1. DEFAULT VALUE CHANGED: redirect(location, code=302, Response) → redirect(location, code=303, Response)
   File: src/flask/helpers.py:241
   Impact: 7 callers rely on the default:
     auth.py:25   `return redirect(url_for("auth.login"))`
     auth.py:77   `return redirect(url_for("auth.login"))`
     auth.py:105  `return redirect(url_for("index"))`
     blog.py:81   `return redirect(url_for("blog.index"))`
   Review: Verify callers expect the new default value

2. DEFAULT VALUE CHANGED: App.redirect(self, location, code=302) → App.redirect(self, location, code=303)
   File: src/flask/sansio/app.py:935
   Impact: 7 callers rely on the default
   Review: Verify callers expect the new default value

Based on real output from GitScope run against Flask commit eca5fd1d. Output lightly condensed for readability — run the command yourself to see the full version.

What GitScope is

GitScope is a verification layer for code changes. Not a review tool — reviews give opinions, GitScope gives facts. It uses tree-sitter AST analysis to detect structural changes in git diffs and traces their impact through your codebase.

What it catches: Function signature changes, removed/renamed symbols, default value changes — and shows you every caller affected.

What it doesn't catch: Logic bugs, behavioral changes beyond signatures, performance issues, security vulnerabilities.

When there's nothing structural to report, it stays silent (exit code 0, no output).

Quick Start

pip install gitscope
gitscope review main..feature

Exit codes: 0 = nothing noteworthy, 1 = findings, 2 = error.

How It Works

1. Parses the diff using tree-sitter AST analysis (not regex)
2. Extracts symbols — functions, classes, signatures
3. Detects high-signal changes — signature changes, removed symbols, default value changes
4. Scans for callers — finds files that reference changed symbols
5. Outputs actionable context — or stays silent if nothing matters

Why not X?

vs CodeRabbit — CodeRabbit reviews code on their servers for $15–30/seat/month. GitScope runs locally, is free, and does a different kind of analysis: structural verification rather than LLM-powered review. They're complementary — CodeRabbit reviews intent, GitScope verifies structure.

vs GitHub Copilot / claude-code-action — Complementary, not competitive. Run GitScope first as cheap, instant structural triage. Then let the expensive model focus on what actually matters.

vs Aider repo-map — Aider's repo-map uses tree-sitter too, but it's locked inside Aider. GitScope works with any agent, any workflow, any CI pipeline.

Agent Integration

Add to your CLAUDE.md, .cursorrules, or equivalent:

Before reviewing PRs, run: gitscope review <ref-range> --format json
Exit code 1 means findings — read the JSON output.
Exit code 0 means nothing noteworthy — proceed normally.

JSON output for programmatic consumption:

gitscope review main..feature --format json

Languages

• Python (most mature — extensive real-world validation)
• TypeScript / JavaScript
• Go
• More planned (Rust, Java, C#)

Philosophy

1. Silence is a feature. No findings? No output. Most diffs don't need structural analysis.
2. Local-first. Your code never leaves your machine. No SaaS, no API keys, no accounts.
3. Agent-native. CLI + JSON output. pip install and go. Works with any agent or workflow.
4. Precision over recall. We'd rather miss a minor issue than cry wolf on every PR.

Roadmap

• v0.2 — GitHub Action, TypeScript/JS improvements
• v0.3 — Persistent symbol graph (.gitscope/ directory)
• v0.4 — gitscope callers, gitscope deps, gitscope impact queries
• Future — 8 language support, review rules engine

License

Apache 2.0 — see LICENSE for details.