Commit Defender

Commit Defender reviews local Git changes and shows source-linked findings in VS Code: inline comments, CodeLens, Problems, and a saved review summary. Review staged changes, a saved file, a directory, or a repository using your own model provider. Add local Memory and Skills or connect to Git Code Reviewer (GCR) to reuse earlier PR discussions and published review guidance.

Manual reviews work without a GCR server. Automatic reviews start disabled. Reviews do not edit files, run tests, or create commits.

• Get started
• Choose a provider
• Review and understand the result
• Memory, Skills, and earlier PR reviews
• Automatic reviews and hooks
• Commands · Settings · Troubleshooting

Get started

Run Commit Defender: GCR Connection Settings or use the sidebar connection menu to open Commit Defender Settings → Memory & GCR. Choose GCR connection & sync… there to configure the connection. The bundled English guide and 한국어 연결 가이드 cover reader keys, local model selection, synchronization, and the first review, and can be read offline. Commit Defender: Open Settings and the sidebar gear open the same settings editor.

1. Install Commit Defender (pydemia.commit-defender) from Marketplace, or use Extensions → Install from VSIX… with a supplied package. Open a trusted Git workspace.
2. Open Commit Defender Settings → Account & Model, then choose Choose account & model… or Configure API destination & key…. The same flows are available as Commit Defender: Use Account and Use API Credential in the Command Palette. Both save only to User Settings; cancelling a step leaves the current selection unchanged.
3. Use Account checks the existing Codex, Claude Code or Antigravity CLI login and server connection, lists the account's models, then offers supported effort. Auth files and OS credentials remain owned by the CLI. A missing login offers sign-in and retry; model IDs are not entered manually. Codex's frozen fixed-source executor supports effort up to xhigh; Claude may offer max. Antigravity uses only exact effort variants returned by its catalog. Use API Credential asks for provider, endpoint, deployment/model, supported effort and a password-protected API key (or an existing destination-bound key). Azure optionally asks for the deployment's actual model to identify documented effort support. Unknown models/custom endpoints and adapters without an effort parameter keep the server default. API setup verifies local credential storage; API/model access is checked when review runs, without a billable setup probe.
4. Save and stage a small change. Run Commit Defender: Analyze Staged Files. Use Analyze Current File for a saved, unstaged file.
5. Open Show Summary Panel and check the report status, findings, and source evidence. Enable automatic reviews after the first manual review works.

Requirements and platform coverage

• VS Code 1.90+, Git, and a trusted repository/worktree.
• A configured provider and an available OS credential store: Windows Credential Manager with local NTFS, macOS Keychain, or Linux Secret Service. Locked or unavailable storage does not fall back to plaintext.
• Node.js 22+ for the independent automatic-review service. Ordinary extension workers use VS Code's runtime. The separate legacy hook requires Node.js 18+ on its PATH.
• A GCR connection and reader key only when using central history or guidance.

2.12.6 provides x64 (amd64) and ARM64 packages for Windows, macOS, and Linux. Codex account review was verified on Windows ARM64 and, for this release, in a Linux ARM64 Extension Host on WSL2 with Codex 0.153.4 and gpt-5.6-luna / high. The Linux run verified the finding, source evidence, encrypted history, and process cleanup using the existing Linux login.

Earlier macOS account reviews used 0.153.4/0.154.0, and macOS ARM64 package regression passed in W04. The new macOS VSIX has not been run on a Mac. Linux x64 isolation was tested with actual CLI binaries under Docker emulation. Windows x64 and Intel Mac execution remain unverified; a package target alone does not establish native execution coverage. See platform packages and Linux setup for prerequisites, account-storage requirements, and the verification matrix.

See Installation for source builds and Windows support and recovery for the verified environment. Installing an extension does not reload an already open window. Finish active work and reload when convenient.

Choose a provider

Gemini CLI is no longer offered in account selection. Existing geminicli settings are preserved; choose Antigravity explicitly when migrating. Commit Defender does not migrate tokens or modify either CLI profile. The Gemini API provider remains available.

No provider or model is silently substituted. A GCR connection does not select a server model or change your local account choice.

Example User Settings for Codex:

{
  "commitDefender.aiProvider": "codex",
  "commitDefender.model": "gpt-5.6-luna",
  "commitDefender.reviewReasoningEffort": "high",
  "commitDefender.reviewMode": "standalone",
  "commitDefender.localProfile": "default"
}

Choose a model/effort available to your account. Set commitDefender.codexPath if discovery does not find the intended executable. The extension does not replace your global CLI or change its default account/model settings.

Example Azure destination settings, before storing the key:

{
  "commitDefender.aiProvider": "aoai",
  "commitDefender.endpoint": "https://YOUR_RESOURCE.openai.azure.com",
  "commitDefender.model": "YOUR_DEPLOYMENT",
  "commitDefender.apiVersion": "2024-08-01-preview",
  "commitDefender.reviewReasoningEffort": ""
}

OpenAI, Anthropic, and Gemini can omit the endpoint to use their adapter's default destination. Select an available model rather than treating an example name as guaranteed account access.

Use API Credential stores a key in encrypted local storage bound to the profile, provider, endpoint, model/deployment, and API version. Changing the destination cannot silently reuse an unrelated credential. Legacy commitDefender.apiKey or hook values require explicit migration with this command. Do not put keys in repository settings. See credential storage and migration.

Review and understand the result

Choose the source

The review captures source, base, and relevant repository context. Unsaved buffers are not captured. Sensitive-file exclusions and source limits apply; excludePatterns can narrow the selection. The model's source tools read only captured material and cannot execute shell commands or edit files. Branch commands ignore uncommitted edits. Merge Impact stops before model execution if Git reports a merge conflict; it does not update either branch, the index or the working tree. Both reviews use the selected account/model and the same local or connected review policy as other manual reviews.

Use Cancel Analysis or the status bar to stop preparation or execution. Cancellation waits for owned work to close. Cancelled and timed-out attempts are not completed reviews with no findings.

Findings, priorities, and history

Findings appear in inline comment threads, CodeLens, and Problems. The summary groups findings by file and retains the Overall Summary, source/context versions, review criteria, and evidence assessment.

Manual and automatic shared-core reviews are advisory. Their P3 findings do not block Git. The separately enabled legacy pre-commit hook has its own blocking policy.

Read the status before interpreting the finding count. completed means the required response and coverage checks finished; it is not a passing test suite. partial, needs-context, failed, cancelled, and superseded have distinct meanings. A source-read entry proves that text was returned, not that a test ran. Invalid evidence references are not accepted as successful review evidence.

When source changes, stale line positions are invalidated. Refresh Local History reloads encrypted saved reports without a model call or automatic restoration of old diagnostics. After a restart, source navigation requires the recorded version to remain recoverable with its matching hash.

Conversations and commit messages

Choose Discuss Review in a summary or history entry to ask about the report and its captured source. Opening a conversation does not call the model; sending a question does. Cancel a turn, reopen saved responses, or answer a clarification with Answer and resume. Missing historical source or changed authorization can prevent continuation. See review conversations.

Commit Defender: Generate Commit Message, available from the Command Palette, Commit Defender sidebar and the commit icon in the Source Control repository header, drafts a message from the staged diff into that repository's SCM input box. Hover over the icon to check its Commit Defender title; the sparkle icon beside the input belongs to GitHub Copilot. Stage the changes first. If the draft changes during generation, the generated message opens separately so the draft is preserved. Progress and failures are recorded in Output → Commit Defender. Edit it before committing; generation does not create a commit. Its account-provider range is broader than fixed-source review, as shown above. The commitDefender.locale setting also controls the generated title and body: ko produces Korean text and en produces English text. Type labels such as [Fix], code identifiers and file paths keep their original spelling.

Generate PR Description asks for a target branch and drafts a title and Markdown body from committed branch changes. The draft opens in an editable document; copy it into your PR after checking its claims. This command does not create a PR or include uncommitted work. A long diff is truncated to the input limit, and the draft then warns you to check omitted changes.

Use Commit Defender Settings → Commit Message to define the final layout. The multiline format supports model fields ($type, $scope, $title, $body) and local Git metadata ($branch, $branchId, $issueId, $prId, $commitId, $date). ${title} is also valid and $$ emits a literal dollar sign. Commit Defender applies the format locally after generation. If a Git variable cannot be resolved from the current repository and branch, no model request is made. See settings.

Memory, Skills, and earlier PR reviews

Local Memory and Skills

Open Local Memory and Skills, choose this worktree or profile, and create a candidate. Record the instruction, applicability, rationale, counter-evidence, and optional expiry. Activate it when ready. Edits or deactivation affect later reviews; existing reports retain the context and revision they used.

For example, a validation rule should identify the request entrypoint and the existing check that would satisfy it. It should not demand a finding solely because an earlier review found a similar bug. Skills provide guidance and cannot grant execution permissions.

Entries and history are encrypted and separated by profile and repository/worktree. They are not uploaded to GCR. Import creates a candidate; export explicitly writes plaintext JSON to your chosen destination. Legacy .commit-defender/**/SKILL.md prompt loading belongs to the separate provider-based path. Use Local Memory and Skills for shared-core reviews.

Connect central history and guidance

1. Obtain the HTTPS server URL and a knowledge:read API key issued for commit-defender from GCR Profile → Clients. The key can allow multiple repositories. It is separate from your model credential.
2. Open Central Review Connection → Connect with API key… and enter the server URL and API key in the password box. Confirm the server; all allowed review sources connect automatically. No repository selection or JSON is required. Choose the public CA certificate if the server uses a private CA.
3. Browse PR review history shows originals, replies, body versions, and linked guidance. View downloaded review knowledge shows the available signed prompts, Skills, criteria, and memories, grouped by readable source name. Reference sources… optionally limits which sources to consult.
4. Run an Analyze command. Relevant active guidance and bounded historical sources are selected locally and pinned for that review.
5. Inspect source URLs, IDs, hashes, and the model's applicability explanation. Inclusion in context and use in a reasoned assessment are separate evidence.

An unregistered local repository can use authorized sources as references. Only a source matching the local Git remote supplies that repository's policy; other repositories do not impose mandatory policy on the current worktree. Import connection JSON… remains available for older server configurations.

A repaired change should be assessed against the requirement without repeating an old defect. Unrelated guidance should be excluded with an applicability explanation. See worked examples.

Connection status shows synchronization, identity, and expiry information. Online manifests have a maximum five-minute freshness window. Use signed offline knowledge requires a valid cached snapshot and signed offline lease; it cannot bypass known revocation, denied access, or expiry. Explicit local fallback is labeled and does not establish central-policy compliance. Use standalone review retains the connection while selecting local context. See central connections and caches.

Automatic reviews and hooks

Open Automatic Reviews and opt into individual triggers for the selected repository/worktree. All four default to off on a new install. Existing preferences are preserved; workspace settings cannot enable automatic execution.

The independent service uses the selected Codex executable, account, model, and reasoning setting. Manual API support does not imply API support for automatic registration. Set serviceNodePath to Node.js 22+ when needed.

Save/Stage events use a three-second debounce. Save starts default to a ten-minute minimum interval; automatic admission allows six review starts per hour in the same profile/worktree. Manual starts count toward this admission budget. These limits count review starts, not tokens or provider billing. Duplicate requests can reuse results, new input cancels obsolete work, and waiting manual reviews take priority over new automatic starts.

Background findings update history and eligible diagnostics without opening a summary or moving focus. Commit/Push normally return after durable enqueue; that does not mean the model finished. Recover Background Review inspects interrupted or saved work. Local Review Activity summarizes saved attempts and findings without model calls or uploads.

Managed hooks preserve existing hook arguments, output, and exit status. The original hook runs first and its failure still stops Git. Advisory findings or service/model failures do not block an otherwise successful hook. Registration uses repository-local core.hooksPath and explicit worktree routes; removing the final route restores the previous setting. Conflicting external changes are preserved and reported.

Use Pause automatic reviews in this worktree or Pause all automatic reviews to suspend admission. Disable Commit/Push in the same menu to remove their managed routes. A running service can differ from the installed extension: let reviews finish and use the documented stop/replacement procedure. Do not delete hooks or kill unrelated Node/Codex processes to update it. See automatic-review behavior and service recovery.

Separate legacy hook

Install Pre-commit Hook and preCommitHook: enable control the older provider-based hook. It can block commits on P3 and has separate prompt, suppression, and credential behavior. It is not required for manual review or the advisory service. Enabling both paths can run two reviews. Uninstall Pre-commit Hook removes that legacy hook, not Automatic Reviews routes.

Legacy severity/richness settings, inline skip comments, and file-based Skills are not permission or policy overrides for the current fixed-source path.

Commands

All names below have the Commit Defender: prefix in the Command Palette.

Settings

Open Commit Defender: Open Settings for account/model setup, commit-message formatting, review and display preferences, global automation defaults, Memory/GCR actions and CLI paths. Changes to editable fields are applied with Save User Settings; Discard edits leaves stored settings unchanged. Account and API setup use the existing verified flows and masked credential input.

The Side Panel separates Review Actions, Current Findings, Settings & Connections, and History. Provider/Model rows open Account & Model; the title gear opens the settings editor, and the refresh icon reloads local history. See Settings for scopes, overrides and troubleshooting.

For workspace overrides and remaining legacy settings, use VS Code Settings in the editor or Settings: Open VS Code Settings from the Command Palette. Each setting below uses the commitDefender. prefix. Store execution choices in User Settings.

locale (en, with ko available) controls model-written review text in the shared and legacy review paths. severityLevel (moderate) and richnessLevel (moderate) apply to the legacy reviewer. These preferences do not replace shared-core review criteria or grant source/tool access.

Privacy and local data

The selected model provider receives captured source and applicable context. Account reviews use the existing CLI account; API reviews use the destination-bound credential.

GCR communication is read-only: server-known repository/PR/history IDs, cursors, and revisions retrieve history and signed guidance. Local code, diffs, questions, reports, conversations, and personal Memory are not uploaded to GCR. There is no central model proxy or downloaded executable-check runner.

Local records are encrypted and scoped by user, profile, repository/worktree, and central audience where applicable. Credential-store failure, invalid signatures, and access denial remain failures. Keys are not placed in new settings or hook JSON. Explicit exports and model requests have different data boundaries from encrypted local history.

Troubleshooting

Use the Commit Defender Output channel and report problem codes to diagnose failures. Include versions and the failing operation in an issue; omit credentials and private source.

For more detail: Installation, standalone review, how-to examples, feature specification, and architecture.