Gitron

AI-powered Git branch code reviewer — review diffs, create pull/merge requests, and manage your GitHub/GitLab workflow from the terminal.

Supports Claude (Anthropic), OpenAI, and Gemini (Google)

Table of Contents

• Installation
• Quick Start
• Commands
  • Review
  • config
  • providers
  • models
  • create-mr
  • close-mr
• Providers & Models
• Configuration File
• How Reviews Work
• Review Output Format

Installation

npm install -g gitron

Requirements: Node.js >= 16.0.0

Quick Start

# Fully interactive — prompts for everything on first run
gitron

# Pass branches directly
gitron feature/my-branch main

# Pass branches + provider + model
gitron feature/my-branch main --provider claude --model claude-sonnet-4-6

On first run, Gitron walks you through a one-time setup wizard to save your default provider, model, and API key to ~/.gitron.json. You won't be prompted again.

Commands

Review (default command)

Compare two branches and get an AI-powered code review.

gitron [compare] [base] [options]

| Argument | Description | |-------------|------------------------------------| | [compare] | Branch with your changes | | [base] | Target branch to compare against |

| Flag | Description | |-----------------------------|--------------------------------------------------| | -p, --provider <provider> | AI provider: claude, openai, or gemini | | -m, --model <model> | Model to use (e.g. claude-sonnet-4-6, gpt-4o)| | -k, --key <apikey> | API key (overrides saved config and env var) |

Examples:

# Fully interactive
gitron

# Positional branches only
gitron feature/auth main

# Specify everything via flags
gitron feature/auth main --provider openai --model gpt-4o --key sk-xxx

The review is saved to a markdown file in the current directory.

config

View or update your saved defaults in ~/.gitron.json.

gitron config [options]

| Flag | Description | |-----------------------------|----------------------------------------------------------| | --show | Print current saved configuration | | -p, --provider <provider> | Set default provider | | -m, --model <model> | Set default model | | -k, --key <apikey> | Set API key for the current/specified provider | | --github-token <token> | Save GitHub personal access token (needs repo scope) | | --gitlab-token <token> | Save GitLab personal access token (needs api scope) |

Examples:

# Show current config
gitron config --show

# Switch default provider
gitron config --provider gemini

# Set a new API key
gitron config --key sk-ant-xxxxxxxxxx

# Save GitHub token for create-mr
gitron config --github-token ghp_xxxxxxxxxx

# Save GitLab token for create-mr
gitron config --gitlab-token glpat-xxxxxxxxxx

# Set provider + model + key at once
gitron config --provider openai --model gpt-4o --key sk-xxxxxxxxxx

providers

List all supported AI providers and highlight your current default.

gitron providers

Example output:

  Claude (Anthropic) (claude)  ← default
  OpenAI (openai)
  Gemini (Google) (gemini)

models

List all available models for a given provider and highlight your saved default.

gitron models <provider>

| Argument | Description | |--------------|--------------------------------------| | <provider> | One of: claude, openai, gemini |

Examples:

gitron models claude
gitron models openai
gitron models gemini

create-mr

Create a Pull Request (GitHub) or Merge Request (GitLab) using the platform's REST API. The platform is auto-detected from your git remote URL.

If the compare branch is behind the base branch, a warning is shown before the MR/PR is created.

gitron create-mr <compare> <base> --title "PR title" [options]

| Argument | Description | |-------------|-----------------------------------------| | <compare> | Source branch (the branch with changes) | | <base> | Target branch (e.g. main) |

| Flag | Description | |------------------------------|------------------------------| | -t, --title <title> | PR / MR title (required) | | -d, --description <desc> | PR / MR description |

Examples:

# Create a GitHub PR
gitron create-mr feature/login main --title "Add login feature"

# With a description
gitron create-mr feature/login main --title "Add login feature" --description "Implements OAuth2 login"

On first use, Gitron will prompt for your GitHub or GitLab personal access token and save it automatically. You can also set it in advance:

gitron config --github-token ghp_xxxxxxxxxx
gitron config --gitlab-token glpat-xxxxxxxxxx

Supported remote URL formats:

| Format | Example | |--------|---------| | GitHub SSH | [email protected]:owner/repo.git | | GitHub HTTPS | https://github.com/owner/repo.git | | GitLab SSH | [email protected]:group/repo.git | | GitLab HTTPS | https://gitlab.com/group/subgroup/repo.git | | Self-hosted GitLab | https://gitlab.company.com/group/repo.git |

close-mr

Close an existing Pull Request (GitHub) or Merge Request (GitLab).

gitron close-mr <number>

| Argument | Description | |------------|------------------------------------------| | <number> | PR number (GitHub) or MR IID (GitLab) |

Examples:

# Close PR #42
gitron close-mr 42

Providers & Models

| Provider | Key name in config | Models | |-------------------|---------------------|-----------------------------------------------------------------------------------------------| | Claude | claude | claude-sonnet-4-6, claude-opus-4-6, claude-haiku-4-5-20251001 | | OpenAI | openai | gpt-4o, gpt-4-turbo, gpt-3.5-turbo | | Gemini | gemini | gemini-2.5-flash, gemini-2.5-flash-lite, gemini-2.0-flash, gemini-2.0-flash-lite, gemini-1.5-pro, gemini-1.5-flash |

Where to get API keys:

• Claude: console.anthropic.com
• OpenAI: platform.openai.com/api-keys
• Gemini: aistudio.google.com

Configuration File

All settings are saved to ~/.gitron.json in your home directory.

{
  "defaultProvider": "claude",
  "defaultModel": "claude-sonnet-4-6",
  "anthropicApiKey": "sk-ant-xxxxxxxx",
  "openaiApiKey": "sk-xxxxxxxx",
  "geminiApiKey": "AIzaxxxxxxxx",
  "githubToken": "ghp_xxxxxxxx",
  "gitlabToken": "glpat-xxxxxxxx"
}

All fields are optional — missing values are prompted interactively on first use and then saved automatically.

Resolution priority for provider / model / API key:

CLI flag  →  saved ~/.gitron.json  →  interactive prompt (saved for next time)

How Reviews Work

1. Provider, model, and API key are resolved (flag → saved config → prompt).
2. Branches are resolved (positional args → interactive prompt).
3. Git diff is fetched between the two branches. Missing branches are auto-fetched from origin.
4. The diff is chunked at file boundaries (≤ 6 000 tokens per chunk) to stay within model context limits.
5. Each chunk is sent to the AI for review. A progress bar tracks multi-chunk reviews.
6. If there are multiple chunks, a synthesis step combines all partial reviews into one final report.
7. The final review is saved to a markdown file in the current directory.

API calls automatically retry up to 3 times with exponential backoff (10 s → 20 s → 40 s) on transient failures.

Review Output Format

Each review produces a structured markdown report covering:

| Section | Details | |---------------------|-------------------------------------------------------------------------| | MR Score | 0–100 score with a one-line summary | | Verdict | APPROVE, REQUEST CHANGES, or COMMENT | | Issues | File, line, description (🔴 high / 🟡 medium / 🟢 low), and solution | | Suggestions | Improvement ideas with recommendations | | Positive Aspects| What was done well | | Standard Practices | Notes on coding standards and conventions | | Summary | Overall assessment paragraph |

Local Development

# Clone and install dependencies
git clone https://github.com/niteshsinghal10/gitron.git
cd gitron
npm install

# Run from source (no build needed)
npm run dev

# Compile TypeScript to dist/
npm run build

# Test the built CLI locally
node bin/gitron.js --help

Author

Nitesh Singhal — GitHub

License

ISC