parcky-cli 2026.6.0a2

AI-powered git commit and PR creation tool

AI CLI 🤖

AI-powered git commit and pull request creation tool using Google Gemini.

✨ Features

• 🤖 AI-Powered Commits: Generate conventional commit messages using Google Gemini (latest google.genai package)
• 📋 Smart Pull Requests: Create PR titles and descriptions automatically
• 🚀 Auto Push: Automatically push commits to remote repository
• 📁 Smart Commit All: Commit all changes grouped by folder and context
• 🔗 Branch-based PRs: Create PRs based on all changes in a branch
• 🎯 Conventional Commits: Follows the conventional commits specification
• 🛡️ Type Safety: Fully typed with mypy support
• 🧪 Well Tested: Comprehensive test suite with pytest
• 📦 Professional Structure: Clean architecture with proper separation of concerns
• ⚙️ Pydantic Settings: Modern configuration management with validation
• 📋 Taskipy Integration: Convenient task runner for development workflow

🏗️ Architecture

The project follows a clean architecture pattern with well-defined layers:

src/ai_cli/
├── core/           # Domain models, interfaces, and exceptions
├── services/       # Business logic and orchestration
├── infrastructure/ # External integrations (Git, AI, GitHub)
├── cli/           # Command-line interface
└── config/        # Configuration management

Layers Overview

• Core Layer: Domain models, business interfaces, and custom exceptions
• Services Layer: Business logic and workflow orchestration
• Infrastructure Layer: External service integrations (Git, AI APIs, GitHub CLI)
• CLI Layer: User interface and command handling
• Config Layer: Environment-based configuration management

🚀 Installation

Requirements

• Python 3.13 or higher (recommended)
• Git
• GitHub CLI (optional, for PR creation)
• Google Gemini API key

Quick Setup

1. Install using uv (recommended):

   # Clone and install
   git clone <repository-url>
   cd ai-cli
   uv sync
   
   # Install globally
   uv tool install .
   

2. Configure your API key:

   # Interactive setup (easiest)
   ai-cli setup
   
   # Or set directly
   ai-cli setup --api-key YOUR_API_KEY
   

   Get your API key from: https://makersuite.google.com/app/apikey

3. Start using:

   ai-cli smart-commit    # AI-powered commits
   ai-cli create-pr       # Create PRs
   ai-cli --help          # See all commands
   

Alternative Setup Methods

Manual .env configuration

# Generate .env file with all options
python scripts/env-gen.py --stdout  # Preview
python scripts/env-gen.py           # Generate local .env
python scripts/env-gen.py --global  # Generate global config

Install GitHub CLI (optional, for PR creation)

# macOS
brew install gh

# Ubuntu/Debian
sudo apt install gh

# Windows
winget install GitHub.cli

6. Install globally (to use in other projects):

   uv tool install .
   

   Configuration is stored at ~/.config/ai-cli/.env

📖 Usage

Basic Usage

Stage your changes and run the smart commit:

git add .
ai-cli smart-commit

Available Commands

# Basic commit (with push)
ai-cli smart-commit

# Commit without pushing
ai-cli smart-commit --no-push

# Commit with automatic PR creation
ai-cli smart-commit --pr

# Auto-confirm all prompts
ai-cli smart-commit --yes

# Commit ALL changes with smart grouping by folder
ai-cli smart-commit-all

# Create PR based on current branch changes
ai-cli create-pr

# Create PR against specific base branch
ai-cli create-pr --base develop

# Create a new GitHub repository
ai-cli create-repo my-project --visibility public --description "My project"

# Show version
ai-cli version

Command Reference

Command	Description
setup	Configure ai-cli with your API key (interactive or direct)
config	Show configuration status and manage models
config -s	Interactive model selection from history
config -m MODEL	Set model directly
smart-commit	Create AI-powered commit from staged changes
smart-commit-all	Commit all changes with smart grouping by folder
create-pr	Create PR based on current branch changes
create-repo	Create a new GitHub repository
version	Show version information

🤖 Model Selection

Easily switch between AI models with the interactive selector:

ai-cli config --select   # or -s

This shows a list of previously used models:

🤖 Select AI Model
┏━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ # ┃ Model            ┃ Status   ┃
┡━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ 1 │ gemini-2.0-flash │ ● current│
│ 2 │ gemini-1.5-flash │          │
│ 3 │ gemini-1.5-pro   │          │
└───┴──────────────────┴──────────┘

Commands: [1-9] select | [n] new model | [d1-d9] delete | [q] quit

• Press a number to select a model
• Press n to add a new model
• Press d + number (e.g., d2) to delete a model from history
• Press q to quit

Or set directly: ai-cli config -m gemini-2.0-flash

Environment Variables

Variable	Description	Default
GEMINI_API_KEY	Google Gemini API key (required)	-
GEMINI_MODEL	Gemini model to use	gemini-2.5-flash
GEMINI_SYSTEM_INSTRUCTION	AI system instruction	Default DevOps instruction
MAX_DIFF_SIZE	Maximum diff size for AI analysis	10000
DEFAULT_BRANCH	Default git branch	main
DEBUG	Enable debug mode	false

🎨 Customizing AI Prompts

You can customize all AI prompts by editing the prompts.json file. The tool looks for prompts in this order:

1. ./prompts.json (project directory - highest priority)
2. ~/.config/ai-cli/prompts.json (global config)
3. Built-in defaults (fallback)

Available prompts:

Key	Description
commit_message	Prompt for generating commit messages
pull_request	Prompt for generating PR title and description
file_correlation	Prompt for analyzing which files should be committed together
system_instruction	System instruction for the AI model

Example prompts.json:

{
  "commit_message": {
    "description": "Prompt for generating commit messages",
    "prompt": "Generate a commit message following Conventional Commits..."
  },
  "pull_request": {
    "description": "Prompt for generating PR content",
    "prompt": "Create a title and description for a Pull Request..."
  }
}

This allows you to:

• Change the language of generated messages
• Modify the commit message format
• Customize PR templates
• Adjust AI behavior per project

🔧 Development

Setup Development Environment

# Install development dependencies
uv sync --group dev

# Install pre-commit hooks
pre-commit install

Code Quality

# Format code
uv run ruff format src tests

# Lint code
uv run ruff check src tests

# Fix lint issues automatically
uv run ruff check src tests --fix

# Type checking
mypy src

# Run all checks
uv run task check

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=src/ai_cli

# Run only unit tests
pytest tests/unit

# Run only integration tests
pytest tests/integration

Project Structure

ai-cli/
├── src/ai_cli/              # Main application code
│   ├── core/                # Domain layer
│   │   ├── models.py        # Domain models
│   │   ├── interfaces.py    # Abstract interfaces
│   │   └── exceptions.py    # Custom exceptions
│   ├── services/            # Business logic layer
│   │   └── smart_commit_service.py
│   ├── infrastructure/      # Infrastructure layer
│   │   ├── git_repository.py    # Git operations
│   │   ├── ai_service.py        # AI integration
│   │   └── pr_service.py        # GitHub PR service
│   ├── cli/                 # Presentation layer
│   │   └── main.py          # CLI interface
│   └── config/              # Configuration layer
│       └── settings.py      # App configuration
├── tests/                   # Test suite
│   ├── unit/               # Unit tests
│   ├── integration/        # Integration tests
│   └── conftest.py         # Test fixtures
├── pyproject.toml          # Project configuration
├── README.md               # This file
└── .env.example            # Environment template

🔄 Workflow

The AI CLI follows this workflow:

1. Analyze: Examines staged git changes
2. Generate: Creates commit message using AI
3. Review: Presents suggestion for user approval
4. Commit: Creates git commit with the message
5. Push: Pushes changes to remote (optional)
6. PR: Creates pull request with AI-generated description (optional)

🎯 Conventional Commits

The tool generates commits following the Conventional Commits specification:

<type>(<scope>): <subject>

[optional body]

[optional footer]

Supported Types

• feat: New features
• fix: Bug fixes
• docs: Documentation changes
• style: Code style changes
• refactor: Code refactoring
• test: Test additions/modifications
• chore: Maintenance tasks
• build: Build system changes
• ci: CI/CD changes
• perf: Performance improvements
• revert: Reverts previous commits

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and quality checks
5. Commit using conventional commits
6. Push to your branch
7. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• Google Gemini for AI capabilities (using latest google.genai package)
• Typer for CLI framework
• Rich for beautiful terminal output
• Ruff for fast linting and formatting
• Conventional Commits for commit standards
• Pydantic for settings management and validation
• Taskipy for task automation

📞 Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information
3. Include error messages and environment details

---

Made with ❤️ by developers, for developers.