Generate AI-powered natural-language summaries of git diffs for code review in any git repository.
Supports OpenAI, Anthropic, Google Gemini, Amazon Bedrock, Mistral, Cohere, Groq, xAI, DeepSeek, or any OpenAI-compatible gateway.
- Ways to use it
- Requirements
- Installation
- Provider configuration
- Usage
- AI coding agent skills (no API key)
- GitHub Action
- Examples
- Used By
- License
| Use it as | Best for | API key |
|---|---|---|
| AI coding agent skills | Asking Claude Code, Copilot, or another coding agent to summarize your branch or draft release notes | Not needed; your agent writes the summary |
| CLI or library | Scripts, tooling, and your own pipelines | Your own provider |
| GitHub Action | A summary on every pull request in CI | Your own provider |
To try the skills in Claude Code:
/plugin marketplace add mcarvin8/smart-diff
/plugin install smart-diff@smart-diff
Then ask your agent to "summarize my branch against main". For GitHub Copilot and other agents, see AI coding agent skills.
- Node.js 22.22.1+
- For the CLI, library, and GitHub Action: an LLM provider credential (see Provider configuration). Not needed for the agent skills or
--emit-context. - No git binary required, on any platform — smart-diff reads the git repository directly via
@scolladon/tsgit, a pure-TypeScript git implementation with zero native dependencies
npm install @mcarvin/smart-diffsmart-diff is "configured" when isLlmProviderConfigured() returns true — i.e. at least one supported provider can be resolved from env vars — or you pass your own llmModelProvider factory. Otherwise summarizeGitDiff / generateSummary throw with LLM_GATEWAY_REQUIRED_MESSAGE.
LLM_PROVIDER explicitly selects a provider. When unset, the resolver auto-detects in this order: LLM_BASE_URL/OPENAI_BASE_URL → openai-compatible, OPENAI_API_KEY/LLM_API_KEY → openai, then ANTHROPIC_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY (or GOOGLE_API_KEY), MISTRAL_API_KEY, COHERE_API_KEY, GROQ_API_KEY, XAI_API_KEY, DEEPSEEK_API_KEY, AWS_ACCESS_KEY_ID/AWS_PROFILE → bedrock, and finally OPENAI_DEFAULT_HEADERS/LLM_DEFAULT_HEADERS → openai.
Provider (LLM_PROVIDER) |
Endpoint | Credential env vars | Default model |
|---|---|---|---|
openai |
OpenAI Chat Completions | OPENAI_API_KEY or LLM_API_KEY |
gpt-4o-mini |
openai-compatible |
Chat Completions at LLM_BASE_URL/OPENAI_BASE_URL |
LLM_BASE_URL or OPENAI_BASE_URL (required); OPENAI_API_KEY/LLM_API_KEY or custom headers |
gpt-4o-mini |
anthropic |
Anthropic Messages API | ANTHROPIC_API_KEY |
claude-haiku-4-5-20251001 |
google |
Gemini Generative Language API | GOOGLE_GENERATIVE_AI_API_KEY or GOOGLE_API_KEY |
gemini-2.0-flash |
bedrock |
Bedrock Converse API (in-house SigV4 signing) | AWS_ACCESS_KEY_ID+AWS_SECRET_ACCESS_KEY (+ optional AWS_SESSION_TOKEN), or AWS_PROFILE pointing at a profile in ~/.aws/credentials; region from AWS_REGION/AWS_DEFAULT_REGION/~/.aws/config (default us-east-1). SSO, instance-role, and container credentials are not supported — static credentials only. |
anthropic.claude-3-5-haiku-20241022-v1:0 |
mistral |
Mistral Chat Completions API | MISTRAL_API_KEY |
mistral-small-latest |
cohere |
Cohere Chat API (v2) | COHERE_API_KEY |
command-r-08-2024 |
groq |
Groq Chat Completions API | GROQ_API_KEY |
llama-3.1-8b-instant |
xai |
xAI Chat Completions API | XAI_API_KEY |
grok-2-latest |
deepseek |
DeepSeek Chat Completions API | DEEPSEEK_API_KEY |
deepseek-chat |
LLM_*wins overOPENAI_*where both exist.
| Variable | Purpose |
|---|---|
LLM_PROVIDER |
Explicit provider id from the table above. |
LLM_MODEL |
Overrides the per-provider default model id. |
OPENAI_BASE_URL / LLM_BASE_URL |
Base URL for an OpenAI-compatible gateway; presence alone auto-selects the openai-compatible provider. |
OPENAI_DEFAULT_HEADERS / LLM_DEFAULT_HEADERS |
JSON object of extra headers merged onto OpenAI / OpenAI-compatible requests (e.g. RBAC tokens, raw Authorization). LLM_* overrides OPENAI_* key-by-key. |
LLM_PROVIDER_NAME |
Display name used when openai-compatible is active (defaults to openai-compatible). |
OPENAI_MAX_DIFF_CHARS / LLM_MAX_DIFF_CHARS |
Max size of unified diff text sent to the model (default ~120k characters). |
OPENAI_MAX_TOKENS / LLM_MAX_TOKENS |
Max completion tokens (default 4000). |
LLM_TEMPERATURE |
Sampling temperature, clamped to 0–2 (default 0.2). Lower = more deterministic; higher = more varied prose. |
LLM_MAX_RETRIES |
Retry count for transient LLM call failures — rate limits, 5xx, network errors (default 2). Set to 0 to disable retries. |
$env:OPENAI_API_KEY = "sk-..."
# Optional: $env:LLM_MODEL = "gpt-4o"$env:ANTHROPIC_API_KEY = "sk-ant-..."
$env:LLM_MODEL = "claude-3-5-sonnet-latest" # optional override$env:OPENAI_BASE_URL = "https://llm-gateway.example.com"
$env:OPENAI_DEFAULT_HEADERS = '{"x-company-rbac":"your-rbac-token-here","Authorization":"Bearer sk-your-api-key-here"}'
# LLM_PROVIDER is auto-detected as "openai-compatible" because LLM_BASE_URL/OPENAI_BASE_URL is set.$env:GOOGLE_GENERATIVE_AI_API_KEY = "..."
$env:LLM_MODEL = "gemini-2.0-flash"Use smart-diff as a library, or as the smart-diff CLI binary that ships with the package via the bin field — no separate install. Provider configuration is identical either way; see Provider configuration. Every option below has a library form (a key in the summarizeGitDiff object) and, where applicable, an equivalent kebab-case CLI flag.
import { summarizeGitDiff } from "@mcarvin/smart-diff";
const { summary, usage } = await summarizeGitDiff({
from: "origin/main",
to: "HEAD",
cwd: "/path/to/repo", // optional; default process.cwd()
includeFolders: ["src"],
excludeFolders: ["node_modules", "dist"],
commitMessageExcludeRegexes: ["^\\[bot\\]"],
commitMessageIncludeRegexes: ["^feat:"], // optional; OR across patterns
teamName: "Platform",
systemPrompt: undefined, // optional; overrides DEFAULT_GIT_DIFF_SYSTEM_PROMPT
systemPromptAppend: undefined, // optional; appended to every system prompt, incl. map-reduce
provider: "anthropic", // optional; overrides LLM_PROVIDER env + auto-detection
model: "claude-3-5-sonnet-latest", // optional
maxDiffChars: 120_000, // optional; also see LLM_MAX_DIFF_CHARS
});
// summary: Markdown string
// usage: LlmUsageReport aggregated across every LLM call — see Token usage reporting belownpm install @mcarvin/smart-diff
npx smart-diff origin/main HEAD --team Platform --max-diff-chars 20000
npx smart-diff --help<from>(required) and[to](defaultHEAD) can be passed positionally or via--from/--to.- Pass
--merge-base/-balongside<from>/--fromto resolve it as the merge base oftoandfrominstead of using it directly — e.g.--to develop --from main --merge-baseis the tsgit-native equivalent of--to develop --from $(git merge-base develop main), with no local git binary required. - Repeatable options (
--include,--exclude,--commit-include,--commit-exclude) accept multiple flags. - The Markdown summary is printed to stdout; errors go to stderr and exit with code 1.
- Run
smart-diff --helpfor the full flag reference, orsmart-diff --versionfor the installed version.
| Option | CLI flag | Description |
|---|---|---|
from / to |
<from> [to] / --from / --to |
Git refs for the range; to defaults to HEAD. |
mergeBase |
--merge-base, -b |
Resolve from as the merge base of to and from, in-process via tsgit — no local git binary needed. |
cwd / git |
--cwd <path> |
Working directory path, or inject your own GitClient instance (library only; see Lower-level API). |
includeFolders |
--include <path> |
Limit diff to these paths relative to repo root (omit for full repo minus excludes). |
excludeFolders |
--exclude <path> |
Excluded paths, applied client-side to the changed-path list (directory-prefix match), e.g. node_modules. |
commitMessageIncludeRegexes |
--commit-include <regex> |
If any pattern is non-empty, only commits whose full message matches at least one pattern are kept (after excludes). Case-insensitive. |
commitMessageExcludeRegexes |
--commit-exclude <regex> |
Drop commits whose message matches any of these patterns. |
teamName |
--team <name> |
Adds a Team: line to the user payload for the model. |
systemPrompt |
--system-prompt <text> |
Replaces the default system prompt. |
systemPromptAppend |
--prompt-file <path> (repeatable) |
Extra instructions appended to every system prompt (single-call, map, and reduce). The CLI reads and joins the files. |
provider |
--provider <id> |
LlmProviderId — wins over LLM_PROVIDER env and auto-detection. |
model |
--model <id> |
Chat model id; overrides LLM_MODEL and the provider default. |
llmModelProvider |
— (library only) | () => Promise<ChatModel> — bypass env-based resolution entirely; hand-wire your own ChatModel (required in tests or custom setups). |
Token reduction — see Handling large diffs
| Option | CLI flag | Description |
|---|---|---|
maxDiffChars |
--max-diff-chars <n> |
Caps unified diff size for the request; see LLM_MAX_DIFF_CHARS. |
mapReduce |
--map-reduce |
Split an oversized diff into per-file batches instead of hard-truncating it. |
contextLines |
--context-lines <n> |
Number of context lines around each change (git diff -U<n>). Lower values (1 or 0) are the single biggest token saver on modification-heavy diffs. |
ignoreWhitespace |
--ignore-whitespace |
Passes -w / --ignore-all-space to git diff so pure-whitespace hunks don't consume tokens. Also applies to --numstat / --name-status so counts stay consistent. |
stripDiffPreamble |
--strip-diff-preamble |
Removes low-value lines from the unified diff (diff --git, index, mode changes, similarity/rename/copy metadata). --- a/…, +++ b/…, and @@ hunk headers are kept. |
maxHunkLines |
--max-hunk-lines <n> |
Caps the body of each hunk; anything past the limit is replaced with a single elision marker. The @@ header and DiffSummary totals are preserved. |
excludeDefaultNoise |
--exclude-default-noise |
Skips the built-in DEFAULT_NOISE_EXCLUDES names (lockfiles, dist, build, out, coverage, node_modules, __snapshots__) at any depth, so nested lockfiles and build folders in monorepos are skipped too. excludeFolders stays repo-root relative. |
| Option | CLI flag | Description |
|---|---|---|
maxRetries |
--max-retries <n> |
Retry count for transient LLM call failures; see LLM_MAX_RETRIES. |
| Option | CLI flag | Description |
|---|---|---|
redactSecrets |
--redact-secrets |
Masks likely secrets/credentials in the diff text before it's sent to the LLM — cloud provider keys, VCS/chat tokens, PEM private key blocks, JWTs, Bearer headers, basic-auth URL passwords, and generic KEY=value assignments. Uses DEFAULT_SECRET_PATTERNS unless secretPatterns overrides them. |
secretPatterns |
— (library only) | Overrides the built-in secret-detection rules used when redactSecrets is true. |
| Option | CLI flag | Description |
|---|---|---|
— (summarizeGitDiff always returns usage) |
--usage |
Print the same LlmUsageReport as Token usage reporting to stderr, after the Markdown summary on stdout. |
| — | -h, --help |
Show CLI help. |
| — | -v, --version |
Print the installed version. |
— (use buildGitDiffSummaryContext) |
--emit-context |
Skip the LLM call and print the prompts as JSON. See Emitting the prompts without an LLM call. |
| — | --out <path> |
Write the summary (or --emit-context JSON) to this file instead of stdout. |
| — | --out-dir <dir> |
With --emit-context: write each prompt to its own Markdown file in <dir> and print a JSON manifest of the paths. |
For most repos, the cheapest wins are:
await summarizeGitDiff({
from: "origin/main",
contextLines: 1, // -U1 cuts 30-60% of tokens on typical diffs
ignoreWhitespace: true, // drop pure-whitespace hunks entirely
stripDiffPreamble: true, // kill `index`/`mode`/`similarity` lines
maxHunkLines: 400, // truncate monster hunks but keep the @@ header
excludeDefaultNoise: true, // skip lockfiles, dist/, coverage/, node_modules/
});These options only reshape the unified diff text — the structured DiffSummary still reports true file counts and line totals, so the model always sees the full change inventory.
By default, a diff over maxDiffChars is hard-truncated — only the first N characters are sent, and a notice is prepended to the summary. Set mapReduce: true to instead split the diff into per-file batches, summarize each batch independently, then synthesize one final summary from the batch summaries:
await summarizeGitDiff({
from: "origin/main",
maxDiffChars: 20_000,
mapReduce: true, // no-op when the diff already fits within maxDiffChars
});This costs one extra LLM call per batch plus one reduce call, so it's slower and more expensive than a single request — use it when losing coverage of the tail of a large diff matters more than latency/cost. systemPrompt (if set) applies to the reduce phase only; the map phase always uses DEFAULT_MAP_REDUCE_MAP_SYSTEM_PROMPT. systemPromptAppend / --prompt-file is appended to both phases, so domain rules reach every batch.
summarizeGitDiff returns the Markdown summary plus token usage aggregated across every LLM call made to produce it — one call by default, or every map-reduce batch plus the reduce call when mapReduce is used:
import { summarizeGitDiff } from "@mcarvin/smart-diff";
const { summary, usage } = await summarizeGitDiff({ from: "origin/main" });
// usage: { requestCount, inputTokens, outputTokens, totalTokens, cachedInputTokens }This reports token counts only — no dollar cost estimate, since per-token pricing varies by provider/model and changes over time; a hardcoded price table would drift out of date. Fields are 0 when a provider doesn't report a given figure. generateSummaryWithUsage is the lower-level equivalent of generateSummary.
If you want full control — for example, to hit an in-process mock, add your own middleware/logging, or talk to a provider smart-diff doesn't support directly — pass llmModelProvider. A ChatModel is just an object with a generate method:
import { summarizeGitDiff, type ChatModel } from "@mcarvin/smart-diff";
const myModel: ChatModel = {
async generate({ system, prompt, temperature, maxOutputTokens }) {
const res = await fetch("https://my-llm-gateway.example.com/v1/chat", {
method: "POST",
headers: { authorization: `Bearer ${process.env.MY_GATEWAY_KEY}` },
body: JSON.stringify({ system, prompt, temperature, maxOutputTokens }),
});
const data = await res.json();
return {
text: data.text,
usage: { inputTokens: data.inputTokens, outputTokens: data.outputTokens },
};
},
};
const { summary } = await summarizeGitDiff({
from: "origin/main",
llmModelProvider: async () => myModel,
});See Examples for ChatModel wrappers that add extra context to the request.
- Single unified diff for
from..towhen no commit-message filters apply and the filtered commit list matches the full log for that range. - Concatenated per-commit patches (each commit diffed against its first parent, or the empty tree for a root commit) when you use include/exclude regexes or when the filtered commit list differs in length from the full range (so the diff reflects only the commits that remain).
--emit-context (library: buildGitDiffSummaryContext(options)) runs everything except the LLM call. It reads the repo, resolves the merge base, applies path and commit filters, shapes and redacts the diff, and batches it under --map-reduce. Then it returns the exact prompts summarizeGitDiff would send. It needs no provider credentials, so a model you already drive can write the summary. The agent skills work this way.
The result is a SummaryContext:
mode: "single":systemPromptanduserContentfor one call.mode: "map-reduce":mapSystemPromptand onemapUserContentsentry per batch. Run each batch, then passreduceUserContentPrefixand the batch outputs tobuildReduceUserContent()for the final call withreduceSystemPrompt.
In both modes, prepend notice (a truncation or map-reduce notice, or "") to the final summary to match summarizeGitDiff's output.
# JSON on stdout
smart-diff main --merge-base --emit-context --redact-secrets
# One Markdown file per prompt, plus a manifest of paths on stdout
smart-diff main --merge-base --emit-context --map-reduce --out-dir ./ctx--provider, --model, --max-retries, and --usage have no effect with --emit-context.
The package also exports helpers for building a custom pipeline on top of the same git and LLM behavior:
- Git:
createGitClient(cwd?, timeout?)(async — returnsPromise<GitClient>, a live@scolladon/tsgitrepository handle; callgit.dispose()when done),getRepoRoot,getCommits,getDiff,getDiffSummary,getChangedFiles,filterCommitsByMessageRegexes,buildPathFilterPredicate,matchesAnyPath,renderFileDiff,renderUnifiedDiff,buildFileSummary,mergeFileSummariesByPath,summarizeFiles,shapeUnifiedDiff,redactSecrets,DEFAULT_NOISE_EXCLUDES,DEFAULT_SECRET_PATTERNS—timeoutis in milliseconds; omit for no timeout - AI:
generateSummary,generateSummaryWithUsage,buildGitDiffSummaryContext,buildSummaryContext,buildReduceUserContent,resolveLlmMaxDiffChars,resolveLlmMaxRetries,truncateUnifiedDiffForLlm,splitUnifiedDiffIntoFileChunks,groupDiffChunksByBudget - Provider resolution:
resolveLanguageModel,detectLlmProvider,isLlmProviderConfigured,defaultModelForProvider,resolveLlmBaseUrl,parseLlmDefaultHeadersFromEnv - Constants:
DEFAULT_GIT_DIFF_SYSTEM_PROMPT,DEFAULT_MAP_REDUCE_MAP_SYSTEM_PROMPT,DEFAULT_MAP_REDUCE_REDUCE_SYSTEM_PROMPT,LLM_GATEWAY_REQUIRED_MESSAGE - Types:
LlmProviderId,LlmModelProvider,ChatModel,ChatCallOptions,ChatResult,ChatUsage,ResolveLanguageModelOptions,GenerateSummaryInput,SummarizeFlags,SummaryContext,LlmUsageReport,DiffFileSummary,DiffSummary,CommitInfo,GitClient,GitDiffRangeQuery,DiffPathFilter,DiffShapingOptions,PathFilterPredicate,RenderedFileDiff,SecretRedactionRuleDiffFileSummary.binary?: booleanistruewhen either blob sniffs as binary; absent for text files
smart-diff ships three Agent Skills that work in Claude Code, GitHub Copilot, and other coding agents that support skills:
| Skill | Who writes the summary | Needs an API key |
|---|---|---|
smart-diff-agent |
Your coding agent, from smart-diff's own prompts via --emit-context |
No |
smart-diff-provider |
Your configured provider, via the CLI | Yes |
smart-diff-salesforce |
Your coding agent by default, or your configured provider if you ask | No (optional) |
Install:
# Claude Code (type these inside a Claude Code session)
/plugin marketplace add mcarvin8/smart-diff
/plugin install smart-diff@smart-diff
# GitHub Copilot CLI (reads the same marketplace files)
copilot plugin marketplace add mcarvin8/smart-diff
copilot plugin install smart-diff@smart-diff
# Any agent, with the skills CLI (skills.sh.json points it at plugins/smart-diff/skills)
npx skills add mcarvin8/smart-diff
# Any agent, with the GitHub CLI
gh skill install mcarvin8/smart-diff --agent github-copilotThen ask your agent to "summarize my branch against main" or "draft release notes since v1.2.0". With smart-diff-agent, smart-diff still reads, filters, redacts, and batches the diff locally, and the agent follows the same system prompts the CLI would send. For oversized diffs it summarizes each batch, in subagents when the agent supports them, and then combines them. Tokens count against your agent's plan instead of a provider key. Requires Node.js 22.22.1+.
In a Salesforce DX project (one with an sfdx-project.json), smart-diff-salesforce limits the diff to the packageDirectories (plus any manifest/ folder with package.xml or destructiveChanges*.xml) and appends a Salesforce release prompt with --prompt-file. The summary is grouped by metadata type and calls out destructive changes, security and access changes, deployment risks, and testing focus. For a CLI plugin with the same goal, see sf-git-ai-meta-insights.
smart-diff is also published as a GitHub Action (marketplace name smart-diff-ai) — no git binary or Node install needed on the runner, since it runs on node24 from a pre-bundled executable.
- uses: actions/checkout@v7
with:
fetch-depth: 0 # full history so `from`/`to` refs resolve
- name: Summarize diff
id: smart-diff
uses: mcarvin8/smart-diff@v6
with:
from: ${{ github.event.pull_request.base.sha }}
to: ${{ github.event.pull_request.head.sha }}
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
- name: Comment summary on PR
uses: peter-evans/create-or-update-comment@v5
with:
issue-number: ${{ github.event.pull_request.number }}
body: ${{ steps.smart-diff.outputs.summary }}Provider credentials are read from the environment exactly as they are for the CLI — set the relevant secret(s) (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.; see Provider configuration) via the step's env: block. Set provider explicitly if more than one provider's credentials are present in the environment.
| Input | Description | Default |
|---|---|---|
from |
Start ref (older side of the range). Required. | |
to |
End ref. | HEAD |
merge-base |
Resolve from as the merge base of to and from. |
false |
working-directory |
Working directory of the git repository. | runner checkout dir |
include |
Only include these paths (newline-separated). | |
exclude |
Exclude these paths (newline-separated). | |
commit-include |
Only keep commits matching these regexes (newline-separated, OR). | |
commit-exclude |
Drop commits matching these regexes (newline-separated). | |
team |
Team label added to the LLM prompt. | |
system-prompt |
Overrides the default system prompt. | |
prompt-file |
Files appended to every system prompt (newline-separated paths). | |
provider |
LLM provider id. | auto-detected |
model |
Model id override. | provider default |
max-diff-chars |
Caps unified diff size sent to the model. | |
max-retries |
Retry count for transient LLM call failures. | 2 |
map-reduce |
Batch an oversized diff instead of hard-truncating it. | false |
context-lines |
Context lines per hunk (git diff -U<n>). |
3 |
ignore-whitespace |
Drop pure-whitespace hunks. | false |
strip-diff-preamble |
Strip diff --git/index/mode noise lines. |
false |
max-hunk-lines |
Elide hunk bodies longer than this many lines. | |
exclude-default-noise |
Skip lockfiles/dist/build/coverage/node_modules at any depth. | false |
redact-secrets |
Mask likely secrets/credentials before sending the diff to the LLM. | false |
| Output | Description |
|---|---|
summary |
Markdown summary of the diff. |
request-count |
Number of LLM calls made to produce the summary. |
input-tokens |
Sum of input (prompt) tokens across all calls. |
output-tokens |
Sum of output (completion) tokens across all calls. |
total-tokens |
Sum of total tokens across all calls, as reported by the provider. |
cached-input-tokens |
Sum of cached input tokens read across all calls (0 if unsupported/unreported). |
Optional examples in examples/ wrap your configured provider with llmModelProvider to give the model extra context alongside the regular diff. Both keep your existing provider and send the added context to it, so expect more input tokens.
| Example | Adds | Requires |
|---|---|---|
| Documentation context | Excerpts from a public documentation URL, fetched with Parallel Search MCP — useful for dependency migrations | npm run build in this repo, then npm ci in examples/parallel-docs |
| Structural diff context | Entity-level changes from Sem's structural diff for the same commit range | sem on PATH and npm run build in this repo |
See each example's README for setup and usage.
This package is used downstream by:
- sf-git-ai-meta-insights — Salesforce metadata wrapper compatible with Salesforce DX projects
- gitlab-llm-kit — TypeScript toolkit for GitLab REST API access and LLM-powered insights (merge requests, issues, pipelines, security, releases, wiki, and more)