Plain-diff local mode

Run PR-Agent against a raw unified diff with no platform API token and no PR URL. Results are printed to stdout (and optionally saved to a file). This suits security-first or air-gapped environments where HTTP access tokens are avoided, and enables pre-push hooks or CI pipelines that operate on a diff artifact rather than a live pull request.

Usage

Pipe a diff directly from stdin:

git diff main...feature-branch | python -m pr_agent.cli --stdin review

Or pass a diff file and save the output alongside stdout:

git diff main...feature-branch > changes.diff
python -m pr_agent.cli --diff-file changes.diff --output review.md review

Flags

Flag	Description
--stdin	Read a unified diff from stdin
--diff-file <path>	Read a unified diff from a file
--output <path>	Write Markdown produced by a compatible Plain Diff command to a file in addition to stdout
--json-output <path>	Write the parsed review and token usage to a JSON file (review or review_pr only, also available with --pr_url)

--stdin and --diff-file are mutually exclusive. At least one must be provided to enter plain-diff mode; omitting both falls back to the normal --pr_url flow. Output options must appear before the command. For example, use --stdin --output result.md review, not --stdin review --output result.md.

Supported commands

review, improve, describe, and ask are supported, along with their review_pr, improve_code, describe_pr, and ask_question aliases. Because there is no hosting platform to push to, improve renders its code suggestions as a single markdown document to stdout (and to --output, if given) instead of as committable inline suggestions. Commands that require live platform interaction (such as update_changelog or similar_issue) are not meaningful in this mode.

Existing command variants that publish Markdown without additional platform state (auto_review, config, settings, and help) also honor --output. answer does not: it requires issue-comment history, which is unavailable when the input is a standalone diff.

How it works

1. Diff parsing — the unified diff is parsed locally into per-file patch objects. Binary files are skipped automatically.

2. Working-tree enrichment — when PR-Agent is run inside the repository working tree, it reads each changed file from disk and reverse-applies the diff to reconstruct the base (pre-change) file content. Having both the base and head versions available gives the LLM full file context, which produces higher-quality analysis.

3. Patch-only fallback — if a changed file cannot be found on disk (e.g. the diff was generated elsewhere, or the file was deleted), PR-Agent falls back to patch-only mode for that file. The review still runs; it simply has less context.

4. Output — the result is written to stdout. If --output <path> is given, it is also written to that file (UTF-8, overwritten on each run). For review or review_pr, if --json-output <path> is given, the parsed review plus a usage object with the run's accumulated token counts is also written to that file as JSON.

No platform token, no PR URL, and no internet access are required for the diff processing step itself. An LLM API key is still needed unless you configure a local model.

Difference from the local git provider

The existing git_provider = "local" mode (invoked with --pr_url) computes a diff by comparing branches in a local Git repository and requires a clean working tree. The plain-diff mode is different in the following ways:

	local provider	plain-diff provider (this page)
Input	Branch names in a local repo	A unified diff supplied via stdin or file
Working tree required	Yes (clean)	No
Platform token required	No	No
Output	GitHub-style comment published locally	stdout (+ optional file)
Inline comments	Not supported	Not supported

Use the plain-diff provider when you already have a diff artifact (e.g. from a CI step or git format-patch) and want a zero-configuration, token-free review.