gitscope 0.1.0

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

GitScope

Catches the bugs that pass code review.

The catch

Flask PR #5898 changed redirect()'s default from 302 to 303. Here's what GitScope finds:

$ gitscope review main..feature

⚠ GitScope: 2 changes need review

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

2. BREAKING CHANGE: dispatch_request(self) → dispatch_request(self, ctx: AppContext)
   File: src/flask/app.py:965
   Impact: 3 external callers need updating:
     views.py:78   `return current_app.dispatch_request()`
     views.py:110  `rv = self.dispatch_request()`
   Review: These callers will break — missing required argument

A code reviewer sees 302 → 303. GitScope sees 5 callers that silently break.

What GitScope is

GitScope is a verification layer for code changes, not a review tool. Reviews give opinions — GitScope gives facts. It uses AST-powered structural analysis of git diffs to catch signature changes, removed symbols, and default value changes, then shows you exactly which callers are affected. 100% precision: when it speaks, it's right. When there's nothing to say, it stays silent.

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 — They review your code on their servers for $15–30/seat/month. GitScope runs locally, is free, and catches the structural breaks their LLM misses. They comment on every PR; GitScope only speaks when something is actually wrong.

vs GitHub Copilot / claude-code-action — Complementary, not competitive. Run GitScope first as cheap, instant triage. If it finds nothing, the diff is structurally safe. Then let the expensive model review 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
• TypeScript / JavaScript
• Go
• More coming (Rust, Java, C# planned)

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.