RepoDelta turns a pull request into an interactive visual map of what changed across the repository—and helps reviewers judge whether the implementation matches its acceptance criteria.
AI agents can now produce changes faster and at a scale that makes supervising every execution impractical. RepoDelta shifts human oversight to the acceptance boundary: before a result enters the codebase, reviewers can understand and govern what changed without replaying every agent step.
It sits after a human or coding agent has written code and opened a PR:
Human or coding agent
↓ writes code
Pull request + linked Issue + CI
↓ repodelta review
Interactive HTML review brief
↓ inspect evidence and gaps
Human review decision
RepoDelta does not write the change or approve it. It connects the PR's authored requirements and transformation claims to the code, structural relationships, and current-head checks a reviewer can actually inspect.
The Brief carries Issue objectives (O), requirements (R), and guardrails
(G) alongside PR-authored transformation claims (T) and completion
conditions (CC). The default Overview starts with the changed-file
boundary and keeps retained structural context explicit.
Selecting a subject opens its authored statement, source, assessment, and evidence in the same investigation surface. RepoDelta then separates runtime change, verification, and unresolved context before revealing source-linked symbols and exact relationships.
Focused structure also states why each member is present: asserted for an authored selector, matched for a deterministic identity match, suggested for a heuristic candidate, and context for the structural path needed to inspect it. Unresolved provenance stays explicit. These labels describe retrieval, not proof that a requirement or claim was implemented.
For T and CC, a concrete file or symbol named in a Markdown code span can
focus the associated code and relationships. Selector-free or unmatched prose
stays visible without an invented graph mapping, so a reviewer can distinguish
a coding agent's claim from the structure that actually changed. See the
authoring guide.
Adoption is incremental, not all-or-nothing. RepoDelta recognizes normalized common section aliases such as Requirements, Acceptance criteria, Definition of done, and Success criteria, and uses whichever supported sections are present. Missing O/G/T/CC sections do not block a report; they stay absent instead of being guessed from unrelated prose.
Live structure-aware reviews require Python 3.11+, Git, and the external
CodeGraph CLI. Install RepoDelta
once in its own isolated environment with
pipx:
pipx install repodeltaThen either install the supported CodeGraph CLI globally:
npm install -g @colbymchenry/codegraphor make Node.js with npx available; RepoDelta will run its tested scoped npm
package automatically. Do not install the unrelated codegraph package
from PyPI.
This installs RepoDelta from PyPI without modifying any target project's virtual environment. Contributors can use the editable source installation in Usage.
Then review a PR from any directory; no checkout of the target repository is required:
repodelta review --repo owner/repository --pr 123 --output report.htmlOpen report.html in a browser. RepoDelta reads GITHUB_TOKEN when it is set,
otherwise tries the authenticated gh CLI for the configured GitHub host;
public repositories can also use GitHub's unauthenticated limits.
--repo reads live PR, linked-Issue, patch, and check data from GitHub. By
default RepoDelta also fetches the exact PR base and head revisions into a
private temporary workspace, so the command can run from any directory:
repodelta review --repo owner/repository --pr 123 --output build/pr-123.htmlIf a local repository already contains both revisions, use it as an explicit optimization:
repodelta review \
--repo owner/repository \
--pr 123 \
--repo-root /path/to/local/repository \
--output build/pr-123.htmlRepoDelta verifies the fetched revisions against GitHub metadata, creates
private worktrees and separate Codegraph indexes, then removes every owned Git
source, worktree, and index after success or failure. Credentials remain
process-scoped and never enter the Git URL, command arguments, report, or
persisted repository configuration. --no-structural-graph is Codegraph-free
and fetches only the exact head required by deterministic repository scans.
Private repositories use the same GITHUB_TOKEN or authenticated gh
credentials; do not put a token in the command or repository URL. For GitHub
Enterprise Server, name both the API endpoint and the host explicitly trusted
to receive those credentials:
repodelta review \
--repo team/project \
--pr 123 \
--github-api-url https://github.life-white.ukpany.com/api/v3 \
--trusted-github-api-host github.life-white.ukpany.com \
--output report.htmlThe trust option must match the HTTPS API host. RepoDelta refuses to send a token to any other custom host, which protects credentials from an accidental or malicious API URL.
For a network-free smoke test instead:
repodelta review --fixture fixtures/pr574.json --output build/pr574.htmlSee Usage for authentication, structural analysis, CI integration, diagnostics, and advanced commands.
The included RepoDelta review workflow runs on pull requests and can also be started manually for a target repository and PR. Each run places the report link in the job summary and retains the HTML as a GitHub Actions artifact.
The intended loop is simple:
- A human or coding agent opens or updates a PR.
- CI runs RepoDelta against that PR revision.
- The reviewer opens one report and inspects the requirement-to-evidence path, structural change, checks, and unresolved coverage.
- The PR is revised or reviewed using those observations; RepoDelta itself does not make the merge decision.
The complete supported product works without an LLM. A normal
repodelta review run sends no repository content to a model provider;
canonical diff facts, symbols, structural graphs, evidence routing,
assessment, and HTML conclusions remain deterministic.
RepoDelta is also exploring where an LLM can add semantic flexibility without becoming an ungrounded review authority:
| Area | Status | Role |
|---|---|---|
| Full review generation | Supported, deterministic | Produces the complete interactive report and every formal conclusion without a model. |
| T/CC candidate evidence interpretation | Experimental ✓ | In an opt-in shadow run, the LLM classifies bounded deterministic evidence candidates as selected, rejected, or insufficient. It does not change the formal report. |
| Semantic focus filtering | To explore | Test whether a model can filter typed heuristic suggestions after deterministic candidate collection without changing structural facts, coverage, or assessment authority. |
| Less-structured Issue intake | To explore | Test whether a model can interpret less structured intent while preserving authored sources and uncertainty. |
| Architectural overlays and grounded explanations | To explore | Test model-assisted higher-level views and explanations while preserving source links, uncertainty, and deterministic authority. |
The shadow result never changes the formal report, assessment, or merge decision. It is evaluated separately against deterministic selection and frozen human labels. See LLM shadow evaluation for the commands and safety boundary; current and planned experiments are tracked in #211, #224, #225, #226, and #227.
- Usage — local, GitHub, and Actions workflows
- Architecture — canonical stages, ownership, and dependency direction
- Review retrieval design — evidence and structural retrieval contracts
- Evaluation — offline suites, metrics, and gates
- Provenance — source and evidence identity
- Fixture schema — offline input format
- Issue authoring and PR authoring — source contracts for requirements and change claims
- Agent change protocol — the repository's responsibility-closed coding method
RepoDelta runs locally: temporary source fetches and base/head worktrees, Codegraph indexes, deterministic analysis, and final HTML stay on the machine or CI runner where the command executes. A live review calls the configured GitHub API and Git host to collect PR metadata and the exact reviewed source; the optional LLM shadow path is the only mode that sends bounded review content to a model provider.
Tokens are read from environment variables or the authenticated gh CLI and
are not stored in Git URLs, persisted Git configuration, review metadata, or
generated HTML. Generated reports create hyperlinks only for absolute HTTP and
HTTPS URLs. Official GitHub is trusted by default; a custom GitHub API host
must be named explicitly before RepoDelta will send it a token.
RepoDelta is open to anyone interested in exploring how software development should evolve in an AI-native world—how intent is captured, changes are produced and independently verified, and where human judgment and authority should remain.
You can contribute by improving an existing capability, trying RepoDelta on real changes, adding an integration or evaluation case, or bringing a workflow problem worth exploring.
Our current approach connects Issue-authored objectives, requirements, and
guardrails (O/R/G) with PR-authored transformation claims and completion
conditions (T/CC), then compares them with the observed change. See
AGENTS.md and the repository guides for
Issues,
agent changes,
commits, and
pull requests.
For concrete bugs, features, integrations, or implementation work, use Issues.
For broader questions about AI-native software development, independent verification, and the role of human judgment and authority, join GitHub Discussions.
RepoDelta is licensed under the MIT License.