git-lrc Documentation

The Simulator Module is a testing utility designed to validate the interactive review and commit flow of git-lrc in a deterministic, automated, and cross-platform-safe manner. It allows developers to test complex workflows without making real AI API calls or requiring manual browser interaction.

Key Capabilities

• Simulates Terminal Decisions: skip, vouch, abort, and commit.
• Simulates Web Decisions: /commit, /commit-push, /skip, /vouch, and /abort.
• Simulates Race Conditions: Validates 'first-valid-decision-wins' behavior between terminal and web inputs.
• Verifies Side Effects: Checks for precommit artifacts in temporary .git directories, specifically:
  • livereview_commit_message
  • livereview_push_request

While git-lrc is suitable for individual use, teams looking for a complete AI code review suite should use LiveReview.

LiveReview includes all the features of git-lrc but adds:

• Team dashboards
• Organization-level policies
• Review analytics
• Team coordination tools

Learn more at https://hexmos.com/livereview.

The git-lrc storage layer operates strictly within a local boundary, utilizing only the local file system and local SQLite. It does not perform any outbound API calls.

Key security and integrity characteristics include:

• Atomic Writes: Critical files are persisted using a temp-and-rename pattern to prevent partial or truncated writes.
• Database Reliability: SQLite is configured with WAL (Write-Ahead Logging) mode and a busy timeout to handle contention and prevent corruption.
• Permission Enforcement: The system uses a centralized chmod utility to enforce strict permission models (e.g., 0600 for secrets and 0755 for executables).
• Data Sensitivity: The system handles high-sensitivity data including API keys, connector state, review metadata, and hook scripts.

The network layer implements several security controls to ensure safe operations:

• Auth separation: API-key and bearer-token paths are distinct and explicit in operation wrappers.
• URL hygiene: Endpoint normalization centralizes path composition to prevent ambiguity.
• Update source restrictions: The self-update path validates the expected host family before downloading binaries.
• Self-update integrity: Staged binaries are checksum-verified against a release-manifest SHA256 before chmod or installation.
• Timeout controls: Review polling utilizes bounded timeout and cancellation semantics.
• Diagnostic hardening: formatJSONParseError helpers improve detection of unsafe endpoints and assist operator triage.
• Secret-handling hardening: create-key failures avoid echoing response bodies, and connector setup errors redact submitted provider keys.

You can use git-lrc in two ways: automatically during a commit or manually before committing.

Option A: Automatic Review (Pre-commit hook)

When you run git commit, the review launches automatically before the commit is finalized.

git add .
git commit -m "add payment validation"

Option B: Manual Review (Before commit)

Run the review explicitly to inspect changes before deciding how to commit.

git add .
git lrc review          # Run AI review first
# OR: git lrc review --vouch   # Skip AI, vouch personally
# OR: git lrc review --skip    # Skip review entirely
git commit -m "add payment validation"

The tool provides three distinct modes for handling code changes:

• Review: The default mode. The AI analyzes your staged diff and provides inline feedback. Use this during your development cycle to catch issues.
• Vouch: Use this when you have finished iterating with the AI (or personally) and are satisfied. It skips the AI review but records your previous iteration statistics and coverage in the git log, signifying you take responsibility for the code.
• Skip: Use this to bypass both AI review and personal attestation. The git log will record skipped.

git-lrc tracks the quality and responsibility of your commits through three distinct modes:

• Review: The default mode. AI analyzes the staged diff and provides inline feedback. Each cycle of review -> fix -> review counts as an iteration (iter).
• Vouch: Use this when you are satisfied with the code (either after several AI iterations or after a manual check). It skips the AI run but records the previous iteration and coverage statistics.
• Skip: Use this to bypass the review process entirely without making a personal responsibility claim.

Every commit processed by git-lrc includes a review-status line in the git log message. This allows teams to see exactly how much code was reviewed.

• ran (iter:N, coverage:X%): The AI ran a review. iter is the number of review cycles performed, and coverage is the percentage of the final diff that has been AI-reviewed in previous iterations.
• vouched (iter:N, coverage:X%): The user explicitly took responsibility for the commit, recording prior iteration and coverage stats.
• skipped: The review was bypassed without AI analysis or personal attestation.

Example log entries:

LiveReview Pre-Commit Check: ran (iter:3, coverage:85%)
LiveReview Pre-Commit Check: vouched (iter:2, coverage:50%)
LiveReview Pre-Commit Check: skipped

When using git-lrc, you can choose how to handle a commit through three distinct modes. This affects how the AI interacts with your code and how the action is recorded in your Git log.

• Review (Default): The AI analyzes your staged diff and provides inline feedback. It tracks iterations and coverage. Git log entry: ran (iter:N, coverage:X%).
• Vouch: Use this when you have completed several review iterations and are ready to commit. It signifies that you are explicitly taking responsibility for the code. It tracks previous coverage. Git log entry: vouched (iter:N, coverage:X%).
• Skip: Use this when you do not want to review a particular commit. No AI analysis is performed. Git log entry: skipped.

The git-lrc project is distributed under a modified Sustainable Use License (SUL). This license is designed to allow self-hosting and customization while preventing commercial resale.

Key Terms:

• ✅ Source Available: Full source code is available for self-hosting.
• ✅ Business Use Allowed: You can use LiveReview for internal business operations.
• ✅ Modifications Allowed: You can customize the code for your own use.
• ❌ No Resale: You cannot resell the software or provide it as a competing service.
• ❌ No Redistribution: You cannot commercially redistribute modified versions.

For detailed terms, permissions, and prohibited use cases, refer to the LICENSE.md file in the repository.

Choose the appropriate command based on your current stage in the development cycle:

• Review: The standard mode. AI analyzes staged changes and provides inline feedback. Each run is an iteration.
• Vouch: Use this when you have finished iterating and are satisfied. It skips the AI review but records your personal responsibility and prior coverage statistics.
• Skip: Use this to commit without any review or responsibility attestation (e.g., for trivial changes).