gitpr

GitPR CLI 🚀

GitPR CLI is a command-line automation tool that uses Google Gemini, DeepSeek, and Ollama artificial intelligence to analyze your code changes (git diff) or entire files. The tool automatically generates commit messages in the Conventional Commits standard, detailed Pull Request descriptions, and deep Code Reviews aimed at reducing technical debt.

🌐 Website: gitpr.natanfiuza.dev.br · 📂 Repository: https://github.com/gitpr-cli/gitpr.git

---

⚡ Quick Start

1. Installation via PyPI

Install GitPR CLI using pip:

pip install gitpr-cli

2. Seeing It Work (No Configuration)

GitPR ships a guided tour over an example diff. It needs no API key, no Git repository and no connection:

gitpr demo

Guided Tour: Six screens walking through a real example — the diff, the commit message, the code review and the pull request description — with the answers recorded once and replayed. Add --no-tui for plain text, --scenario security-issue for the other example.
📖 Full Documentation: https://gitpr.natanfiuza.dev.br/docs/demo?lang=en_us

3. Initializing in a Repository

To set up GitPR in a folder of a new repository, run:

gitpr --install

Guided Setup: Guided configuration that downloads skill templates, installs Git Hooks, configures MCP for your editors, and verifies the API key for your AI provider.
📖 Full Documentation: https://gitpr.natanfiuza.dev.br/docs/install-wizard?lang=en_us

🛠️ Technologies and Libraries Used

This project was developed in Python and uses the following main libraries:

• Click: To create a robust and user-friendly command-line interface (CLI).
• Google GenAI: Official SDK for direct integration with the Gemini API.
• OpenAI: Library used due to its full compatibility with the powerful DeepSeek API.
• Python-dotenv: For secure environment variable management.
• Pytest: For running unit tests in a simple, colorful, and readable way in the console.
• Cryptography: To ensure your GEMINI_API_KEY is stored encrypted and securely on disk.
• PyYAML: Used to read and process the custom static analysis rules from the .gitpr.linter.yml file.
• Textual: Powerful library for creating Terminal Graphical Interfaces (TUI), used in the interactive issue generation and editing panel.
• Requests: Elegant and robust library for HTTP requests, used to communicate with the GitHub REST API.
• MCP: Official Python SDK for the Model Context Protocol, enabling GitPR to integrate directly with AI-powered editors and IDEs.

---

🧪 Running Tests

To ensure the Git capture logic and AI integration are working correctly, we use unit tests.

1. Install test dependencies (if you haven't already):

   pipenv install --dev pytest
   

2. Run the tests with the command:

   pipenv run pytest -v
   

Pytest will automatically detect files inside the tests/ folder and display a detailed execution report.

---

⚙️ Installation and Configuration

Installing from PyPI (Recommended)

1. Install the package with pip:

   pip install gitpr-cli
   

2. On the first run, the wizard will guide you:

   $ gitpr
   

🚀 Intelligent PR Automation with AI

🔧 First run detected! Let's configure GitPR CLI.

🔑 Enter your GEMINI_API_KEY:

📄 Default output filename pattern [{branch}_{datetime}_PR_DESC.md]:

Note: Your configuration will be securely saved in the ~/.gitpr/.env file.

Note (updates): GitPR is distributed exclusively through PyPI. On every run it checks whether a newer version has been published, and when one exists it blocks the execution and asks you to run pip install --upgrade gitpr-cli. See auto-update.md.

🔒 Security Note: GitPR CLI uses symmetric encryption (Fernet). Your API key is stored as a hash in the .env file, and the master key for decryption is automatically generated in ~/.gitpr/secret.key. Never share your secret.key file.

From Source Code

1. Clone the repository: git clone https://github.com/gitpr-cli/gitpr.git

2. Enter the folder: cd gitpr

3. Install in editable mode:

pip install -e .

4. Run: gitpr

Prefer an isolated environment? Install the dependencies with pipenv install google-genai openai python-dotenv click cryptography and run pipenv run python src/main.py instead.

Note on the update gate: a source install reports the version found in your checkout, so a tree behind the published release is stopped at startup. See Installing GitPR from Source.

💻 How to Use

GitPR has a powerful default behavior and several advanced options to assist you in your day-to-day as a developer.

Default Behavior (Pull Request)

Simply run the bare command in your terminal:

gitpr

The tool will sync with the remote (git fetch), compare your changes with the remote main branch (e.g.: origin/main), and generate a Markdown file (e.g.: feature-login_20260421110134_PR_DESC.md) at the root of your project with the complete suggestion for your Pull Request.

Advanced Options and Commands

You can pass the following flags for specific actions:

• gitpr demo: Guided tour over an example diff that ships with the tool — the commit message, the code review and the pull request description, produced by the real pipeline on a recorded example. Needs no API key, no Git repository and no connection, which makes it the first thing to run on a new machine. Use --scenario <name> for another example, --lang <code> for another language, --no-tui for plain text. 📖 Full docs
• gitpr badge: Adoption badge for your README. Prints the Markdown snippet — --readme prints only the line, --style picks the shields.io style (flat, flat-square, for-the-badge). Nothing is written to your README. Published pull requests carry a badge of their own, with the linter counts of the diff; GITPR_BADGE=false turns it off. 📖 Full docs
• gitpr config: Interactive configuration screen. Opens a master-detail TUI to view, edit, search, and validate all settings stored in ~/.gitpr/.env (with secret encryption and live validation). 📖 Full docs
• gitpr release: Changelog and Release Notes generator. Scans commits since the previous version, categorizes them according to Conventional Commits, suggests a semantic version bump, generates an AI executive summary, and optionally publishes the release to your forge. 📖 Full docs
• gitpr fix [<finding_id>]: Review findings patch application & rollback. Turns findings from the last code review (gitpr -r) into safe, reviewable unified diffs. Includes safety classification (safe, review_required, experimental), --all-safe batching, --force validation, and --rollback <patch-id>. 📖 Full docs
• gitpr split: Atomic commit splitter. Reads uncommitted working tree changes, groups hunks by intent using AI, and proposes ordered atomic commits without altering your working tree files (--dry-run, --apply). 📖 Full docs
• gitpr tests generate: AI test suite generation & scaffolding. Analyzes your diff, a target file (--file), or a review finding (--finding) and generates complete, executable test suites (supporting pytest, jest, vitest, phpunit, pest). Use --apply to write to disk. 📖 Full docs
• gitpr mentor [<finding_id>]: Junior Mentor Pedagogical Explanations. Breaks down code review findings with educational context ("why this matters", real-world analogy, guided questions, and key takeaway) to foster growth and mentor developers. Works standalone over the latest review findings or with --finding <id>. 📖 Full docs
• gitpr explain: Reviewer Guide generator. Generates a concise summary explaining what changed, why it changed, where reviewers should focus, and potential regression risks. 📖 Full docs
• gitpr review-pr <pr_number>: Remote Pull Request review. Fetches and reviews an open pull request directly from the forge (GitHub, GitLab, Bitbucket, Azure DevOps) without checking out the branch locally. Use --post-comment to post the review directly to the PR. 📖 Full docs
• gitpr risk: Local Risk Scoring for Diffs. Computes a deterministic, explainable risk score (0.0 to 100.0) and badge (LOW 🟢, MEDIUM 🟡, HIGH 🟠, CRITICAL 🔴) using local repository signals (critical paths, missing tests, migrations, bug history, and static findings). Use --file <path>, --format json, --base <ref>, or --no-history. Automatically included in code reviews (GITPR_RISK_INCLUDE_IN_REVIEW=true). 📖 Full docs
• gitpr policy: Shared quality policy for the repository. Adopts a versioned YAML Policy Pack — review skills, linter rules, severity overrides, critical paths, risk weights and PR/commit conventions — and records the choice in .gitpr/policy.lock.yml, so the review, the linter and the risk score all run under the same policy, with a checksum per pack. list, validate, show, use, init, install, off. 📖 Full docs
• gitpr baseline: Baseline and auditable suppressions for legacy adoption. Records the findings a repository already has in .gitpr/baseline.json, so a run classifies every finding as new, existing, resolved, ignored or accepted_debt and only new blocks. Every suppression carries a reason, and accepted debt carries an owner and an optional deadline. create, show, validate, update, suppress, unsuppress. 📖 Full docs
• gitpr check: Unified CI check command. Consolidates static linter, secret scanning, external bridges (Semgrep, Gitleaks, Bandit), optional AI code review, risk scoring, and baseline into a single CI pipeline command. Emits machine-readable artifacts in SARIF 2.1.0, JSON, or JUnit XML with deterministic exit codes (0, 1, 2). 📖 Full docs
• -c or --commit: Runs a local git diff and displays only the suggested commit message.
• -r or --review: Performs a detailed Code Review of local changes. Use with --mentor to append pedagogical mentoring explanations for each finding.
• -f or --fullreview: Performs a Full Code Review analyzing all changes since the remote branch. Use with --mentor to append pedagogical mentoring explanations.
• -i <file> or --input <file>: Full File Audit. Must be used together with -r or -f; it ignores git history and does a Code Review of the entire file. Excellent for acting as a consultant on legacy code refactoring.
• --provider <gemini|deepseek|ollama>: Forces the use of a specific AI only for this execution, ignoring your default saved in .env.
• --lang <code>: Forces the interface language for this execution (e.g.: en_us, pt_br). Overrides GITPR_LANG in .env without persisting the change.
• -ch or --chat: Opens the Interactive Pair Programming Chat — a TUI terminal where the AI sees your current diff and maintains a contextual conversation. Features memory per branch, slash commands (/explain, /tests, /optimize, /clear), auto-patching (F5), diff refresh (F2), and session export (F6).
• -l or --linter: Runs only the local static linter (no AI calls). Ideal for use in CI/CD pipelines to block non-compliant code.
• --status: Lists uncommitted file changes categorized as new, modified, and deleted — fast, no AI, no network. 📖 Full docs
• --no-unstaged-check: Skips the unstaged files verification before AI processing for a single invocation. Equivalent to GITPR_SKIP_UNSTAGED_CHECK=true for one run. 📖 Full docs
• --no-suggest-reviewers: Disables the suggested reviewers computation in the interactive PR publisher (default ON). 📖 Full docs
• --explain: Includes the Reviewer Guide section ("Explain my PR") in the Pull Request description. 📖 Full docs
• --init: Interactive SCM forge wizard. Detects the repository's forge (GitHub, GitLab, Bitbucket Cloud, Azure DevOps), configures the provider, and stores the access token encrypted. 📖 Full docs
• --linter-setup: Interactive external linter wizard. Guides you through installing and configuring external linters (ESLint, PHPCS, Stylelint) as a Checkstyle XML bridge. 📖 Full docs
• --mcp: Starts GitPR as an MCP server (Model Context Protocol) on stdio transport. Enables integration with VS Code, Cursor, Claude Desktop, and other MCP-compatible editors — exposing all GitPR AI capabilities as 16 annotated tools, 19 resources, and 7 pre-built prompts directly inside your IDE. Also available as the standalone gitpr-mcp command.
• --plugins: Lists all globally installed plugins — custom linter packs from ~/.gitpr/plugins/linter/ and MCP prompt templates from ~/.gitpr/plugins/prompts/. These plugins apply across all your projects without duplication. 📖 Full docs
• --install: Interactive Setup Wizard. Runs a guided 4-step setup: downloads skill templates, installs Git hooks, configures MCP for detected editors, and checks/requests your AI provider API key. Each step asks for confirmation before proceeding.
• -ih or --installhooks: Automatically installs local Git Hooks (pre-commit and prepare-commit-msg) in your repository.
• -s or --skill: Creates the AI context template files (.gitpr.commit.md, .gitpr.pr.md, .gitpr.review.md, .gitpr.filereview.md, .gitpr.issue.md, .gitpr.blame.md) and the Linter (.gitpr.linter.yml) inside .gitpr/skill/.
• -is or --issue: Automatically generates a draft of a standardized Issue and opens an interactive interface (TUI) for editing or direct submission via REST API. This feature has 3 context engines depending on the command combination:
  • New Code Issue (gitpr -is): Reads the current git diff. Why use: Ideal for quickly documenting the task you just finished programming, before committing.
  • Epic/Release Issue (gitpr -is -ht): Reads the full history of the current branch (Git Log + PR Cache). Why use: Ideal for generating consolidated documentation of an entire release or a large feature that took several days/commits to complete.
  • Archaeological/Technical Debt Issue (gitpr -is -b file:lines): Reads the timeline of a specific business rule. Why use: Ideal for documenting technical debt, explaining how a legacy code block evolved and why it needs to be refactored.
• PR Publisher (default): Running gitpr generates the PR description with AI, saves the .md file to .gitpr/reports/pr_desc/, and opens an interactive terminal interface (TUI) to review, edit, and publish the Pull Request directly to GitHub, GitLab, Bitbucket, or Azure DevOps via REST API. Before generation, it checks for unstaged files, calculates suggested reviewers, and offers a modal to manage them. Use --no-publish to save only the PR file locally without opening the publisher, or --no-edit to auto-commit pending changes (with lint validation), auto-push, and publish immediately — handling existing PR updates, optional auto-merge, and clear error feedback when merge conflicts occur. Use --base <branch> to change the target branch. 📖 Full docs
• -h or --help: Shows the general help with all options. Use together with another flag for contextual help (e.g.: gitpr -h --issue, gitpr -h --linter) with a direct link to the detailed documentation of each feature.
• -u or --update: Checks the latest version of GitPR on PyPI and shows how to update it (Auto-Updater).

⚙️ Technical Note (--hook): GitPR has a hidden flag --hook <file> that is triggered exclusively by the Git Hooks system in the background. It allows the AI to inject the suggested message directly into Git's temporary file, without cluttering your terminal.

⚙️ Technical Note (--pre-save): GitPR has a hidden debug flag --pre-save that can be combined with any AI command (e.g.: gitpr -c --pre-save). Before each AI call, it saves the full payload that will be sent to the model (system instruction + prompt + character counters) to a _{action}-{datetime}.json file in the current folder, and then proceeds normally. Useful for inspecting very large prompts. Note: when the response comes from the local cache, no call is made and no file is generated.

📦 Huge Diffs (Map-Reduce)

When your diff is too large for a single AI call (over ~90k estimated tokens), GitPR automatically splits it into batches by file, asks the AI for a technical summary of each part (Map), and unifies everything into the final commit message, review, or PR description (Reduce). No flags needed — it activates on demand and shows the progress in the console.

📚 Full documentation: docs/map-reduce-diff.md

🛡️ Local Linter (Static Analysis & Security)

GitPR CLI allows you to define strict rules that will be validated instantly during --review or --fullreview, without depending on AI. This is ideal for preventing common errors (like console.log or test IPs) from reaching the repository.

How to configure .gitpr.linter.yml:

When running gitpr --skill, a template will be generated. You can configure rules using Regular Expressions (Regex):

rules:
  - name: "check-localhost"
    extensions: ["js", "php"] # Extensions to be validated
    regex: 'http(s)?://(localhost|127\.0\.0\.1)' # What to look for
    message: "🚨 Localhost usage detected in file {file_name}"
    ignore_comments: true # Ignores if the line is commented
    ignore_paths: # Folders or files ignored (accepts *)
      - "vendor/*"
      - "node_modules/*"

The Linter analyzes only the added lines in your git diff, ensuring a focused and extremely fast execution. If there are violations, they will appear highlighted at the top of your review file.

External Linters & SAST Bridges (Checkstyle Bridge)

If your project already uses tools like ESLint, PHP_CodeSniffer, Stylelint, Semgrep, Gitleaks, or Bandit, GitPR can act as a bridge — running them in the background and filtering errors only for the lines you changed in your current diff. Any linter or SAST scanner that emits reports in the checkstyle format is supported. In addition, GitPR includes embedded secret scanning rules to catch leaked API keys, tokens, and credentials before they leave your machine.

Instead of configuring the YAML manually, use the interactive wizard:

gitpr --linter-setup

The wizard shows pre-configured presets (PHPCS, ESLint, Stylelint — controlled remotely via templates/gitpr.linter-presets.json), guides you through the native installation command (e.g.: npm install --save-dev eslint), and injects the correct external_linters block into your .gitpr.linter.yml.

Every run — manual via --linter or automatic before commits — consolidates the Regex Rules, Embedded Security Rules, and External Linters into a single Markdown report saved at .gitpr/reports/linter/ (customizable via OUTPUT_FILE_NAME_LINTER). The report is generated only when violations are found — clean runs create no files.

⚡ Local Risk Scoring (gitpr risk)

GitPR computes a local, deterministic, and explainable risk score (from 0.0 to 100.0) for individual modified files and the pull request as a whole. It requires no network calls, consumes zero AI tokens, and evaluates repository and Git signals offline:

• Critical Paths & Security (+25): Authentication, billing, credentials, and sensitive operational modules.
• Database & Infra (+20): Migrations, schema definitions, CI/CD workflows, Docker, and Kubernetes configs.
• Missing Tests (+15): Executable production code modified without matching test updates in the diff.
• History Signals (+10 to +20): Files associated with recent bug fixes, reverts, or high commit churn.
• Findings: Blocker (+25) or critical (+15) findings reported by static linters and secret scanners.
• Test Presence (-10): Mitigating credit when test files are added or modified alongside code changes.

Risk Levels & Badges

Level	Score Range	Badge	Meaning
LOW	0.0 – 24.0	LOW 🟢	Routine changes with low regression likelihood
MEDIUM	25.0 – 49.0	MEDIUM 🟡	Moderate changes requiring normal review vigilance
HIGH	50.0 – 79.0	HIGH 🟠	Significant changes touching critical areas or lacking tests
CRITICAL	80.0 – 100.0	CRITICAL 🔴	High regression exposure, blockers, or sensitive architectural impacts

Aggregation Formula (50 / 30 / 20)

The aggregate PR score combines:

• 50%: Maximum individual file score
• 30%: Weighted average of file scores by lines changed
• 20%: Aggregated critical evidence score

Review Integration

When enabled (GITPR_RISK_INCLUDE_IN_REVIEW=true in ~/.gitpr/.env), GitPR automatically appends a ## ⚡ Risk Assessment section to generated code review reports (-r, -f, gitpr review-pr) and primes the AI review prompt with critical risk areas.

gitpr risk                        # Compute risk for current diff
gitpr risk --file src/auth.py     # Decompose risk for a single file
gitpr risk --format json          # Output JSON for CI/CD pipelines
gitpr risk --base main            # Evaluate against specific git base ref

📖 Full documentation: docs/risk-scoring.md

🧾 Adopting GitPR in a Legacy Repository (gitpr baseline)

Adopting GitPR in a repository that already carries hundreds of findings is the moment the tool is least useful: the gate fails on problems nobody in this change introduced, and the alternatives are turning it off or spending a sprint fixing code nobody is touching. A baseline is the record of what the repository already has, committed to Git, so that every run classifies what it finds instead of starting from zero.

gitpr baseline create                    # Record the findings of the current diff
gitpr baseline show                      # The findings, the decisions and the counts
gitpr baseline validate                  # Every defect in the file — exit 1 on any
gitpr baseline update                    # Re-record today's diff, keeping decisions
gitpr baseline suppress <id> --reason "…"    # A decision about one finding
gitpr baseline unsuppress <id>           # Take a decision back

A suppression is not a silent filter: it carries a reason, an author and a date, and accepted debt carries an owner and an optional deadline. --scope finding|line|file|rule widens a decision beyond one finding, and anything wider than a single finding lives in .gitpr/baseline.overrides.yml, where it is reviewed with the code. A checksum over the record catches an edit made outside GitPR — gitpr baseline validate names the divergence instead of applying the file. A Policy Pack may carry a baseline: block of its own, applied in memory and attributed to the pack.

Four variables in ~/.gitpr/.env, also editable through gitpr config in the section Baseline:

Key	Default	Effect
GITPR_BASELINE_ENABLED	true	false → no run reads the baseline: the behaviour of every earlier version, byte for byte
GITPR_BASELINE_PATH	(empty)	.gitpr/baseline.json; a relative path resolves from the repository root
GITPR_BASELINE_REQUIRE_LOCKFILE_CHECKSUM_MATCH	true	A divergent checksum makes the record unusable: the blocking flows refuse and exit non-zero
GITPR_BASELINE_ALLOW_LOCAL_OVERRIDES	true	false → .gitpr/baseline.overrides.yml is not read

Only a new error-level finding exits non-zero, and only new findings carry risk points — everything else reaches the risk report as zero-point evidence with its status. The baseline is never sent to the AI, and no entry stores code or a secret: the file is committed, so only a digest of the offending line is kept.

📖 Full documentation: docs/baseline-suppressions.md

🤝 Co-Author Signature

Every commit message generated by GitPR automatically carries the co-author trailer:

Co-Authored-By: Gitpr-cli <gitpr@natanfiuza.dev.br>

The trailer is appended programmatically (never by the AI) in all flows: console suggestion (gitpr -c), the prepare-commit-msg hook, auto-commit (--no-edit), the PR publication TUI, and the MCP generate_commit_message tool. It is idempotent — never duplicated when the message already contains it — and is hidden from the TUI edit screen, injected only when the commit is executed.

📖 Full documentation: docs/commit-message-ia.md

🏷️ Pull Request Badge

Every pull request GitPR publishes carries a badge at the foot of the body, with what the local linter counted on that very diff:

GitPR | 0 errors · 2 warnings

It is built from a real measurement, never from a claim: red when a blocking finding is there, yellow for advice, green when the rules found nothing — and no badge at all when no linter rules are configured, because a green badge over a diff nobody checked would say something GitPR cannot back. It is on by default; GITPR_BADGE=false turns it off, and gitpr --skill is what gives it rules to count.

For your own README there is a static badge. gitpr badge --readme prints the line and writes nothing — pasting it is your call:

📖 Full documentation: docs/badge.md

🧠 Multi-Model Architecture (AI-Agnostic)

GitPR is not tied to a single Artificial Intelligence. During initial setup, the user can choose their default engine. We currently support:

• Google Gemini (Default: gemini-pro-latest)
• DeepSeek (Default: deepseek-v4-pro)
• Ollama (Local) — run models locally without internet, fully compatible with the OpenAI API format

You can dynamically switch models by configuring the GEMINI_API_MODEL_PRIMARY or DEEPSEEK_API_MODEL_PRIMARY variables in your ~/.gitpr/.env file, or switch in real-time using the --provider flag.

🎯 Customizable "Skills" System (Prompt Engineering)

Instead of hiding AI instructions in the source code, GitPR uses local Markdown files that act as System Instructions. When running gitpr -s, the following files are generated inside .gitpr/skill/ to customize the AI's "persona" according to your company's business rules:

• .gitpr.commit.md: Rules for generating short commit messages.
• .gitpr.pr.md: Required topic structure for the Pull Request description.
• .gitpr.review.md: Defines the architectural focus (e.g.: SOLID, Clean Code) for diff analysis.
• .gitpr.filereview.md: Defines strict cohesion and coupling rules for full file auditing (used with --input).
• .gitpr.issue.md: Defines the structure and level of detail required for generating standardized Issues (used with --issue).
• .gitpr.blame.md: Defines the focus of archaeological analysis for legacy code tracing (used with --blame).
• .gitpr.mentor.md: Defines pedagogical coaching style, analogy framing, and tone for Junior Mentor Mode (used with gitpr mentor or --mentor).

🌐 Internationalization (i18n)

GitPR automatically detects your system language and displays messages in your native language. The i18n system is inspired by Laravel's __() helper:

• Auto-detection: On first run, GitPR detects your OS language and saves it to ~/.gitpr/.env (GITPR_LANG).
• Translation files: Language packs are downloaded automatically from the official repository to ~/.gitpr/langs/.
• 5 languages: English, Portuguese (Brazil), Portuguese (Portugal), Spanish, and French. Packs are versioned (__lang_version__) and self-update automatically (OTA) when a new translation release ships.
• English fallback: If a translation is missing, the English text is displayed directly.
• Developer API: Use from src.i18n import __ and wrap all user-facing strings with __("Your text here").
• Placeholders: Supports named parameters — __("Downloading {file}...", file="template.md").

To force a specific language, set GITPR_LANG=pt_br or GITPR_LANG=en in ~/.gitpr/.env.

📖 Full developer guide: docs/i18n_explanation.md — architecture, usage patterns, circular import precautions, and how to add new languages.

🔄 Hook Scripts Versioning & Auto-Sync

GitPR includes an automatic versioning system for Git hook scripts (pre-commit, prepare-commit-msg, pre-push, post-checkout, post-merge). Every time you run gitpr, the system silently checks whether your installed hooks match the latest version and automatically updates them if needed — all while respecting your language preference.

How it works:

1. Reads SCRIPTS_VERSION and SCRIPTS_INSTALLED_LANG from ~/.gitpr/.env
2. Compares with the latest version (__scripts_version__) shipped with your GitPR release, and with the language you asked for (SCRIPTS_LANG, empty = follow the interface language)
3. If versions or language differ → automatically downloads and updates hooks
4. If everything matches → skips entirely (single .env read, zero network I/O)

Example:

# First run — no hooks installed yet
$ gitpr --installhooks
📥 Downloading pre-commit...
📥 Downloading prepare-commit-msg...
✅ Scripts synced successfully!

# Subsequent runs — silent checks
$ gitpr  # (no output = hooks are up to date)

The system supports 5 languages: English (default), Portuguese (Brazil), Portuguese (Portugal), French, and Spanish. Scripts are thin shims — the real logic lives in the CLI, so even slightly stale hooks continue working correctly.

📚 Full Documentation

🔌 MCP Integration (Model Context Protocol)

GitPR can run as an MCP server, exposing its AI-powered capabilities as tools that your editor's AI assistant can invoke directly — no terminal needed. This enables a fully integrated workflow where you can generate commit messages, review code, run linters, trace code origins, and create issues without leaving your IDE.

Supported Editors

Editor	Config File
VS Code	.vscode/mcp.json
Cursor	.cursor/mcp.json
Claude Code	.mcp.json
Claude Desktop	claude_desktop_config.json
Zed	settings.json

Quick Setup

Use the built-in installer to configure your editor automatically:

gitpr-mcp --install vscode    # Creates .vscode/mcp.json
gitpr-mcp --install cursor      # Creates .cursor/mcp.json
gitpr-mcp --install claude-code # Creates .mcp.json
gitpr-mcp --install claude      # Updates Claude Desktop config
gitpr-mcp --install zed         # Updates Zed settings
gitpr-mcp --install auto      # Auto-detect and install for all found

The installer creates the config directory if needed, merges with any existing config (never overwrites other servers), and is safe to run multiple times.

Manual setup is also supported — see docs/mcp-integration.md for the JSON config format for each editor.

Once configured, use natural language in your editor's AI chat:

• "Review my current changes" → calls review_code
• "Generate a commit message" → calls generate_commit_message
• "Create a PR description" → calls generate_pr_description
• "Run the linter on my diff" → calls run_linter

Available MCP Tools

Tool	Description
get_git_context	Current branch, repository name, and remote URL
analyze_diff	Git diff of uncommitted changes
get_full_diff	Full diff against origin/main
generate_commit_message	AI-generated Conventional Commits message
review_code	AI code review of local changes
full_review	AI code review of all changes since origin/main
generate_pr_description	Complete PR description (title + body)
run_linter	Static linter against .gitpr.linter.yml
analyze_blame	Git blame + AI classification
generate_issue	Structured issue from diff, history, or blame
list_unstaged_files	Uncommitted file changes categorized (new/modified/deleted)
analyze_unstaged_diff	Unstaged diff only (working tree vs index)
list_fix_candidates	Fix candidates of the last review: patch, classification, id (read-only)
review_remote_pr	AI review of a pull request already open on the forge, fetched by number (read-only)
run_check	Structured CI/Editor quality gate returning normalized findings and pass/fail status
publish_pull_request	Publish or update a Pull Request on the remote forge from title and body

Direct CLI Invocation

All GitPR MCP tools can be invoked directly from the terminal without starting the stdio server:

# List all available tools with their parameter signatures
gitpr-mcp --tool

# Invoke a specific tool
gitpr-mcp --tool get_git_context
gitpr-mcp --tool review_code
gitpr-mcp --tool generate_commit_message --tool-args '{"diff_text":"..."}'
gitpr-mcp --tool analyze_blame --tool-args '{"file_path":"src/main.py","start_line":"270","end_line":"284"}'

This is useful for scripting, CI/CD pipelines, and one-off queries where you don't need a persistent MCP server. JSON output goes to stdout; all diagnostic messages go to stderr — safe for piping.

📖 Full documentation: docs/mcp-integration.md — available in 5 languages (EN, PT-BR, PT-PT, ES, FR).

🧩 Official VS Code & Cursor Extension — Prefer native editor commands, SCM toolbar buttons, and inline Problems diagnostics? Install the thin-client extension in extensions/vscode/, powered by gitpr-mcp.

💬 MCP Prompts — GitPR also exposes 7 pre-defined message templates (prompts) for common flows like "Review PR", "Generate Commit Message", and "Create Issue from Diff". See the MCP Prompts guide for the full list.

🎯 Smart Excludes (Token Optimization)

GitPR automatically removes non-code files from your git diff before sending them to the AI — reducing token consumption and API costs with zero configuration required.

Two layers of exclusions:

• Lockfiles & generated files: package-lock.json, *.min.js, *.map, *.pyc, *.svg, and 30+ more patterns defined in gitpr.smart-excludes.json
• Documentation prose: *.md, *.txt, *.rst, *.adoc, *.tex, and 20+ more extensions defined in gitpr.docs-smart-excludes.json

Documentation tracking: Even though documentation content is excluded from the diff, GitPR still tells the AI which documentation files changed by injecting their paths as metadata into the system instructions. The AI has full context about doc updates without consuming tokens on their prose.

Benefits:

• ✅ Up to 98% token reduction on documentation-heavy branches
• ✅ Faster AI responses — less text to process per API call
• ✅ Higher-quality analysis — AI focuses on code changes, not markup
• ✅ Zero configuration — works automatically on every run, managed remotely

Project-local configuration: Each project can define extra exclusions at .gitpr/conf/gitpr.smart-excludes.json. The file is auto-seeded on first run and merged with the global list at runtime:

{
  "_comment": "Project-specific Smart Excludes.",
  "excludes": [
    "dist/",
    "*.pyc",
    "build/",
    "node_modules/"
  ]
}

Add framework-specific build artifacts, generated folders, or any pattern that only applies to this project. The file is safe to commit — your team gets the same exclusions.

📖 Full documentation: docs/smart-excludes.md — available in 5 languages (EN, PT-BR, PT-PT, FR, ES).

📁 Output Directory Structure

By default, GitPR saves all generated files in the .gitpr/reports/ directory, organized by artifact type:

Artifact	Default Location
PR Description	.gitpr/reports/pr_desc/
Code Review	.gitpr/reports/review/
Full Review	.gitpr/reports/full_review/
File Review	.gitpr/reports/file_review/
Blame Report	.gitpr/reports/blame/
Issue Draft	.gitpr/reports/issue/
Linter Report	.gitpr/reports/linter/

Directories are created automatically on first use. Backward compatible: if your .env already contains custom paths with directory separators (e.g., OUTPUT_FILE_NAME=/home/user/prs/my_pr.md), those are honored as-is — GitPR only redirects bare filenames to .gitpr/reports/.

📚 Technical Documentation and Advanced Guides

To keep this README concise, we detail the most advanced DevOps and Continuous Integration focused implementations in separate documents.

If you want to implement GitPR as an automated quality barrier in your team, check out the guides below.

🌐 Each guide is available in 5 languages — add .pt_br, .pt_pt, .fr_fr, or .es_es before the .md extension for translated versions (e.g., docs/understanding_chat_functionality.pt_br.md). English is the default with no suffix.

Chat & Interactive Features

• 🧠 Interactive Chat (Pair Programming) — How to use the AI chat with memory, slash commands, auto-patch, and session export.

DevOps & CI/CD

• Local Git Hooks (Shift-Left) — How to use gitpr --installhooks to create guardrails on the developer's machine and use AI to automatically write commit messages.
• Hook Scripts Versioning & Auto-Sync — How the automatic versioning and i18n-aware synchronization system keeps your Git hooks up to date.
• Customizable Static Linter — How to create validation rules in .gitpr.linter.yml, bridge external linters (ESLint, PHPCS, Stylelint), and generate Markdown reports for CI/CD and pre-commit hooks.
• CI/CD Integration (GitHub Actions) — How to run GitPR in the pipeline to block "Merge" of PRs with violations.

Core Features

• Guided Tour (gitpr demo) — How the gitpr demo subcommand walks through the commit message, the code review and the pull request description over a recorded example, with no API key, no repository and no network.
• Pull Request Badge — What the badge GitPR attaches to published pull requests says, where it is attached, when it is left out, and how to print the static one for your own README.
• Pull Request (Default Mode) — Complete flow for generating PR descriptions without flags.
• Pull Request Publisher TUI — How to review and publish Pull Requests directly to GitHub from the terminal.
• AI Code Review — Guide to review modes (--review, --fullreview), file auditing (--input) and remote pull request review (gitpr review-pr).
• Remote Pull Request Review (gitpr review-pr) — How the gitpr review-pr subcommand reviews a pull request that is already open on the forge, fetching its diff from the API without checking out its branch.
• AI Commit Messages — How to generate messages in the Conventional Commits standard and integrate with Git Hooks.
• Issue Generation and TUI Interface — How to use the terminal graphical interface (TUI) and the 3 context engines to manage structured Issues.
• Code Archaeologist (Git Blame) — How to trace the origin of business rules with git blame and AI.
• Skills and Templates System — How to customize AI behavior with .gitpr.*.md files.
• Release Notes & Changelog (gitpr release) — How the gitpr release subcommand generates the changelog / release notes of a repository from the delta of the previous version, links every commit, pull request and contributor, suggests the next semantic version and publishes releases on the forge.
• Fix Command (gitpr fix) — How the gitpr fix subcommand turns the findings of the last review into patches you read before they touch your tree, classifies each one by safety, and undoes an applied patch on demand.
• Split Command (gitpr split) — How the gitpr split subcommand reads a working tree holding several concerns, groups the hunks by intent with AI, and turns them into ordered atomic commits without ever writing to your files.
• Local Risk Scoring (gitpr risk) — How the gitpr risk command evaluates regression risk, decomposes signals (50/30/20 formula), and highlights high-risk areas in code reviews offline.
• Policy Packs (gitpr policy) — How a repository adopts a versioned Policy Pack that carries skills, linter rules, severity overrides, critical paths and risk weights together, the precedence ladder that combines packs, the lockfile the team commits, and the three failures that abort instead of silently degrading.
• Baseline & Auditable Suppressions (gitpr baseline) — How a legacy repository records the findings it already has, how a run classifies them as new, existing, resolved, ignored or accepted_debt, why only new blocks, what the fingerprint hashes and what it deliberately leaves out, the four scopes of a suppression, the checksum that catches a hand edit, and the baseline: block a Policy Pack may carry.

Configuration & Infrastructure

• Editor Extension (VS Code & Cursor) — Thin-client VSIX extension driving gitpr-mcp over stdio for SCM commit generation, Markdown code reviews, two-step PR publishing, and inline Problems diagnostics.
• Interactive Configuration TUI (gitpr config) — Master-detail terminal interface to view, edit, and validate settings in ~/.gitpr/.env.
• Multi-Forge SCM Integration — Unified SCM provider layer for GitHub, GitLab, Bitbucket Cloud, and Azure DevOps with --init wizard.
• Suggested Reviewers — Automatic reviewer suggestion via Git blame of added lines mapped to forge logins.
• Usage Telemetry & Audit Log — Local invocation logging and audit history for tracking CLI executions.
• Install Wizard — Step-by-step guided setup for configuring GitPR in a new project.
• AI Providers — Configuration and selection between Google Gemini, DeepSeek, and Ollama.
• Auto-Updater — How GitPR's automatic update and the mandatory update block work.
• Architecture — Project architecture, design patterns, and technical stack overview.
• GitHub Token (PAT) Integration and Security — Understand how GitPR creates issues directly in the repository with authentication.
• Internationalization (i18n) — Architecture, usage patterns, and how to add new languages.
• MCP Integration — Connect GitPR to VS Code, Cursor, and Claude Desktop via Model Context Protocol.
• MCP Prompts — Pre-built message templates (7 prompts, 35 language variants) for common GitPR workflows in your editor's AI chat.
• MCP Tool Annotations — IDE integration hints (readOnlyHint, destructiveHint) for smarter UI behavior and safer tool execution.
• Metrics & Telemetry — Local offline analytics for team usage metrics, exportable CSV reports, and interactive TUI dashboard.

⚡ Local Cache System (Quota Savings)

GitPR has an intelligent MD5-based cache engine. Whenever you run a command (--review, --commit, etc.), the tool generates an exact hash of your current code (diff) and instructions. If you run the same command again without changing the code, GitPR intercepts the request and returns the result instantly (in milliseconds) from the ~/.gitpr/cache/prompts/ folder, saving you time and your Gemini API quotas!

🔄 Auto-Updater (Over-The-Air Update)

Never worry about manually downloading new versions again. GitPR has a Connection Guardian and a built-in updater:

• It checks network availability before starting so it doesn't block your offline workflow.
• On each execution, it checks PyPI for a newer published version (cached for 24 hours).
• When a newer version exists, it blocks the execution and asks you to run pip install --upgrade gitpr-cli.
• You can force the check at any time with gitpr --update or gitpr -u — it shows the upgrade command without installing anything.
• Scripts, Git hooks, the MCP server and the contextual help are never blocked.

Publishing to PyPI

pipenv run python -m build
pipenv run twine upload dist/*

🤝 How to Contribute

Contributions are very welcome! To contribute:

1. Fork the project.
2. Create a branch for your feature (git checkout -b feature/NewFeature).
3. Commit your changes (git commit -m 'feat: add new feature'). Tip: Use GitPR itself to generate this message! 😄
4. Push to the branch (git push origin feature/NewFeature).
5. Open a Pull Request.

✨ Acknowledgments and Authorship

Project conceived and developed by:

Natan Fiuza - contato@natanfiuza.dev.br

📄 License

This project is licensed under the GNU Lesser General Public License v2.1 (LGPL-2.1). See the LICENSE file for more details.