🚀 GGPR - PR & Commit AI Assistant

GGPR is an AI-powered CLI tool that supercharges your Git workflow by generating high-quality commit messages, branch names, and pull requests. Save time, improve documentation, and let AI handle the tedious parts of your development process! 🎉

---

✨ See GGPR in action with real PRs and commits

---

🌟 Why GGPR?

• 🕒 Save Time: No more writing commit messages or PR descriptions manually.
• 🧠 AI-Powered: Generate semantic, high-quality commit messages and PRs.
• 🔧 Customizable: Tailor prompts and workflows to your team's needs.
• 🌍 Multiple AI Providers: Choose from OpenAI, Anthropic, Ollama, DeepSeek, and more.
• 🔒 Privacy-Friendly: Use local models with Ollama for complete control.

---

---

✨ Features

• AI-Generated Commit Messages: Create semantic, best-practice commit messages.
• Commit Optimization: Improve existing commit messages with AI suggestions.
• Smart Branch Names: Generate descriptive branch names automatically.
• Automated PR Creation: Generate PR titles, descriptions, and create them in seconds.
• Multiple LLM Support: Choose from OpenAI, Anthropic, Ollama, or DeepSeek.
• Local AI Integration: Use local models via Ollama for privacy and speed.
• GitHub CLI Integration: Seamlessly create PRs via GitHub CLI.

---

📋 Requirements

• Node.js v18+
• Bun (recommended) or npm
• Git v2.25+
• GitHub CLI (required for PR creation and updates, ensure it's installed and authenticated with the necessary scopes)

---

🛠️ Installation

1️⃣ Install GGPR

# Install globally with npm
npm install -g pr-commit-ai-agent

# Or with bun (recommended)
bun add -g pr-commit-ai-agent

# Install GitHub CLI (required for PRs)
brew install gh

# Authenticate GitHub CLI with proper scopes
gh auth login --scopes repo,read:org,read:discussion,gist

# Verify GitHub CLI authentication status and scopes and ensure you have the necessary scopes
gh auth status

# Ensure you have the necessary scopes for PR management
# If required scopes are missing, refresh your token with:
gh auth refresh --scopes repo,read:org,read:discussion,gist

Note on GitHub Tokens: If you use GH_TOKEN or GITHUB_TOKEN environment variables instead of gh auth login, ensure your personal access token has the following scopes: repo, read:org, read:discussion, and gist. These scopes are required for complete PR management functionality.

---

2️⃣ Get Your API Keys 🔑

GGPR supports multiple AI providers. Some offer free credits to get started:

• 🌟 OpenRouter - Free credits and models available!
• 🤖 OpenAI - Industry-leading models.
• 🧠 Anthropic - Advanced AI models.
• 🔍 DeepSeek - Specialized AI solutions.
• 🖥️ Ollama - Local models for privacy.

---

3️⃣ Configure GGPR ⚙️

Option 1: Interactive Setup (Recommended)

# Run the interactive configuration wizard
ggpr config

Option 2: Use Environment Variables

# Set for current session
export LLM_PROVIDER=openai
export OPENAI_API_KEY=your_key_here

# Or pass inline for a single command
LLM_PROVIDER=ollama MODEL=qwen2.5-coder OLLAMA_BASE_URL=http://0.0.0.0:11434/api/generate ggpr

Option 3: Edit Configuration File

• Run ggpr config to locate the config file (e.g., ~/.config/pr-commit-ai-agent-nodejs/config.json).
• Modify the file to set your preferred settings.

---

📝 Usage

Create Command (Default)

Generate AI-enhanced commits, optimize messages, and create PRs.

# Basic usage (interactive)
ggpr

# Auto-confirm all prompts
ggpr --yes

# Log all LLM requests for debugging
ggpr --log-request

# Combine flags
ggpr --yes --log-request

Info Command

Display repository information and status.

ggpr info

# Show detailed information
ggpr info --full

Config Command

Manage your GGPR configuration settings.

ggpr config

---

🚶 Workflow

1. Target Branch Selection: Choose the branch for your PR.
2. Uncommitted Changes: Generate AI commit messages for your changes.
3. Commit Optimization: Improve existing commit messages.
4. Branch Creation: Create a branch with an AI-generated name.
5. PR Creation: Generate a PR with an AI-generated title and description.

Workflow Diagram

flowchart TD
    Start([Start GGPR]) --> InitConfig[Initialize Configs & Settings]
    InitConfig --> GitStatus[Get Git Status]
    GitStatus --> BranchCheck{Determine\nTarget Branch}

    %% Branch Selection Flow
    BranchCheck -->|Find Tracking Branch| TrackingExists{Tracking\nBranch Exists?}
    TrackingExists -->|Yes| ConfirmTracking{Confirm\nTracking Branch?}
    TrackingExists -->|No| FetchRemotes[Fetch Remote Branches]
    ConfirmTracking -->|Yes| UseTracking[Use Tracking Branch]
    ConfirmTracking -->|No| FetchRemotes
    FetchRemotes --> UserSelectBranch[User Selects Branch]
    UserSelectBranch --> ConfirmBranch{Confirm\nBranch Selection?}
    ConfirmBranch -->|Yes| TargetBranchSet[Set Target Branch]
    ConfirmBranch -->|No| ExitProcess([Exit Process])
    UseTracking --> TargetBranchSet

    %% Uncommitted Changes Flow
    TargetBranchSet --> CheckChanges{Working Dir\nClean?}
    CheckChanges -->|Yes| OptimizeCommits[Optimize Commit Messages]
    CheckChanges -->|No| HandleChanges{Commit\nChanges?}
    HandleChanges -->|No| ExitProcess
    HandleChanges -->|Yes| AnalyzeChanges[Analyze Changes with AI]
    AnalyzeChanges --> CollectModified[Collect Modified Files]
    CollectModified --> GetDiffs[Get Diffs for Each File]
    GetDiffs --> AskAI{Send to AI\nfor Analysis?}
    AskAI -->|No| ExitProcess
    AskAI -->|Yes| GenerateCommitMsg[Generate Commit Message]
    GenerateCommitMsg --> ConfirmCommit{Proceed with\nCommit?}
    ConfirmCommit -->|No| ExitProcess
    ConfirmCommit -->|Yes| CreateCommit[Create Commit]
    CreateCommit --> MarkCommit[Mark as Created by Tool]
    MarkCommit --> OptimizeCommits

    %% Optimize Commits Flow
    OptimizeCommits --> CommitsExists{Commits to\nOptimize?}
    CommitsExists -->|No| CheckPRFlag
    CommitsExists -->|Yes| OptimizeConfirm{Optimize\nCommits?}
    OptimizeConfirm -->|No| CheckPRFlag
    OptimizeConfirm -->|Yes| CheckLastCommit[Check Last Commit]
    CheckLastCommit --> IsCreatedByTool{Created by\nThis Tool?}
    IsCreatedByTool -->|Yes| CheckPRFlag
    IsCreatedByTool -->|No| IsMergeCommit{Is Merge\nCommit?}
    IsMergeCommit -->|Yes| CheckPRFlag
    IsMergeCommit -->|No| AnalyzeCommit[Analyze with Full Context]
    AnalyzeCommit --> AINeedsImprovement{Needs\nImprovement?}
    AINeedsImprovement -->|No| MarkNoChanges[Mark as Processed]
    AINeedsImprovement -->|Yes| ConfirmAmend{Amend\nCommit?}
    ConfirmAmend -->|No| CheckPRFlag
    ConfirmAmend -->|Yes| AmendCommit[Amend Commit Message]
    AmendCommit --> MarkAmended[Mark as Created by Tool]
    MarkAmended --> CheckPRFlag
    MarkNoChanges --> CheckPRFlag

    %% PR Creation Flow
    CheckPRFlag{Create PR?} -->|No| Complete([Complete])
    CheckPRFlag -->|Yes| ConfirmPR{Proceed with\nCreating PR?}
    ConfirmPR -->|No| Complete
    ConfirmPR -->|Yes| CheckExistingPR[Check for Existing PR]
    CheckExistingPR --> ExistingPR{PR Already\nExists?}

    %% Existing PR Flow
    ExistingPR -->|Yes| ConfirmUpdate{Update\nExisting PR?}
    ConfirmUpdate -->|No| GeneratePRDetails
    ConfirmUpdate -->|Yes| PushToExisting[Push to Existing PR]
    PushToExisting --> CheckNewCommits[Check for New Commits]
    CheckNewCommits --> UpdatePRDesc{Update PR\nDescription?}
    UpdatePRDesc -->|No| Complete
    UpdatePRDesc -->|Yes| GenerateUpdatedDesc[Generate Updated Title/Description]
    GenerateUpdatedDesc --> ConfirmUpdateDesc{Apply\nUpdates?}
    ConfirmUpdateDesc -->|No| Complete
    ConfirmUpdateDesc -->|Yes| UpdatePR[Update PR Title/Description]
    UpdatePR --> Complete

    %% New PR Flow
    ExistingPR -->|No| GeneratePRDetails[Generate PR Details with AI]
    GeneratePRDetails --> ConfirmPRDetails{Create PR with\nthese Details?}
    ConfirmPRDetails -->|No| Complete
    ConfirmPRDetails -->|Yes| CheckBranchTarget{Current Branch\nis Target?}
    CheckBranchTarget -->|Yes| CreateNewBranch[Create New Branch]
    CheckBranchTarget -->|No| UseCurrentBranch[Use Current Branch]
    CreateNewBranch --> ConfirmNewBranch{Confirm New\nBranch?}
    ConfirmNewBranch -->|No| Complete
    ConfirmNewBranch -->|Yes| CreateBranch[Create Branch]
    CreateBranch --> PushBranch
    UseCurrentBranch --> PushBranch[Push Branch to Remote]
    PushBranch --> CreatePRWithGH{Create PR using\nGitHub CLI?}
    CreatePRWithGH -->|No| ShowManualInstructions[Show Manual PR Instructions]
    CreatePRWithGH -->|Yes| GHCliAvailable{GitHub CLI\nAvailable?}
    GHCliAvailable -->|No| ShowManualInstructions
    GHCliAvailable -->|Yes| CreatePRGH[Create PR with GitHub CLI]
    CreatePRGH --> PRSuccess[PR Created Successfully]
    ShowManualInstructions --> Complete
    PRSuccess --> Complete

    classDef processNode fill:#d4f1f9,stroke:#0e5974,stroke-width:1px;
    classDef decisionNode fill:#ffe6cc,stroke:#d79b00,stroke-width:1px;
    classDef startEndNode fill:#d5e8d4,stroke:#82b366,stroke-width:2px;
    classDef errorNode fill:#f8cecc,stroke:#b85450,stroke-width:1px;

    class Start,Complete,ExitProcess startEndNode;
    class BranchCheck,TrackingExists,ConfirmTracking,ConfirmBranch,CheckChanges,HandleChanges,AskAI,ConfirmCommit,CommitsExists,OptimizeConfirm,IsCreatedByTool,IsMergeCommit,AINeedsImprovement,ConfirmAmend,CheckPRFlag,ConfirmPR,ExistingPR,ConfirmUpdate,UpdatePRDesc,ConfirmUpdateDesc,ConfirmPRDetails,CheckBranchTarget,ConfirmNewBranch,CreatePRWithGH,GHCliAvailable decisionNode;
    class ExitProcess errorNode;
    class InitConfig,GitStatus,FetchRemotes,UserSelectBranch,TargetBranchSet,AnalyzeChanges,CollectModified,GetDiffs,GenerateCommitMsg,CreateCommit,MarkCommit,OptimizeCommits,CheckLastCommit,AnalyzeCommit,MarkNoChanges,AmendCommit,MarkAmended,CheckExistingPR,PushToExisting,CheckNewCommits,GenerateUpdatedDesc,UpdatePR,GeneratePRDetails,CreateNewBranch,UseCurrentBranch,CreateBranch,PushBranch,ShowManualInstructions,CreatePRGH,PRSuccess processNode;

Loading

---

🤝 Contributing

We welcome contributions of all sizes! Here's how you can help:

1. Fork the repo and create a new branch.
2. Make your changes and test them locally.
3. Submit a pull request with a clear description of your changes.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Made with ❤️ by Mohamed Meabed and contributors

⭐ Star us on GitHub • 🐛 Report Bug • ✨ Request Feature