smart-commit-cli 0.1.0

AI-powered Git commit automation

Smart Commit v2

The equivalent of Prettier for Git history

Stop thinking about staging files, commit boundaries, and writing messages. Smart Commit analyzes your changes, proposes logical commits, and lets you review before executing.

Vision

Your Changes
    ↓
Smart Commit Analysis
    ↓
Logical Commit Groups
    ↓
High-Quality Messages
    ↓
Your Review
    ↓
Perfect Git History

Features

• 🤖 AI-Powered Grouping: Uses embeddings and ML to understand which files belong together
• 📝 Automatic Messages: Generates Conventional Commits without manual writing
• 👁️ Interactive Preview: Review all proposed commits before executing
• 🔄 Multi-Provider LLM: Works with OpenRouter, OpenAI, Anthropic, Gemini, Groq, Azure, and more
• ⚡ Local Embeddings: Uses efficient local embeddings for semantic analysis
• 🔐 Safety First: Never modifies history without approval
• ↩️ Undo Support: Easily revert the last Smart Commit session
• 🧩 Plugin System: Extensible architecture with language-specific plugins
• ⚙️ Offline Mode: Works without LLM for pure ML-based clustering
• 🎯 Conventional Commits: Automatic type detection (feat, fix, docs, etc.)

Installation

Requirements

• Python 3.12+
• Git

From PyPI (Coming Soon)

pip install smart-commit

From Source

git clone https://github.com/hamxa296/Smart-Commit.git
cd Smart-Commit
pip install -e .

Quick Start

1. Initialize

smart-commit init

2. Configure LLM (Optional)

smart-commit config --provider openrouter --model anthropic/claude-sonnet --api-key YOUR_KEY

Or set environment variables:

export SMART_COMMIT_PROVIDER=openrouter
export SMART_COMMIT_MODEL=anthropic/claude-sonnet
export SMART_COMMIT_API_KEY=your-api-key

3. Run

smart-commit run

Pipeline

Smart Commit processes changes through 10 stages:

flowchart TD
    A["🔍 Git Status"] --> B["📋 Read Diffs"]
    B --> C["🔎 Static Analysis"]
    C --> D["🌳 AST Analysis"]
    D --> E["📝 Summaries"]
    E --> F["🧠 Embeddings"]
    F --> G["🔗 Similarity Graph"]
    G --> H["🎯 Semantic Clustering"]
    H --> I["✨ LLM Review"]
    I --> J["💬 Commit Messages"]
    J --> K["👁️ Preview UI"]
    K --> L["✅ Git Commit"]
    
    style A fill:#e1f5ff
    style H fill:#f3e5f5
    style I fill:#fff3e0
    style L fill:#e8f5e9

Commands

# Analyze and create commits
smart-commit run

# Preview without executing
smart-commit preview

# Undo last session
smart-commit undo

# Show configuration
smart-commit config --show

# Diagnostic checks
smart-commit doctor

# List plugins
smart-commit plugins

# Show version
smart-commit version

Advanced Options

smart-commit run --yes              # Skip confirmation
smart-commit run --dry-run          # Preview only
smart-commit run --no-ai            # Disable LLM
smart-commit run --offline          # Use only local analysis
smart-commit run --model gpt-4      # Override model
smart-commit run --provider openai  # Override provider

Configuration

Smart Commit looks for configuration in this order:

1. CLI Options (--model, --provider)
2. Environment Variables (SMART_COMMIT_*)
3. Configuration File (~/.smart_commit/config.yaml)
4. Defaults

Example config.yaml

# LLM Settings
provider: openrouter
model: anthropic/claude-sonnet
api_key: your-api-key

# Embedding
embedding_model: all-MiniLM-L6-v2

# Clustering
clustering_method: agglomerative
similarity_threshold: 0.5
max_files_per_commit: 8

# Behavior
interactive: true
auto_push: false
conventional_commits: true
use_local_embeddings: true

Safety & Trust

Safety Features

• ✅ Never modifies history without approval
• ✅ Always shows preview before executing
• ✅ Always supports undo with smart-commit undo
• ✅ Validates all file paths and commit messages
• ✅ Warns about protected branches (main, master, production)

Preview Example

Commit 1
feat(auth): improve login validation and session handling
Files: 3
  ✏️ src/auth/login.ts
  ✏️ src/auth/jwt.ts
  ✏️ src/middleware/auth.ts

Commit 2
docs: update README with auth changes
Files: 1
  ✏️ README.md

Proceed? [y]es [n]o [d]ry-run [e]dit

Plugin System

Plugins provide framework-specific knowledge for better clustering.

Built-in Plugins

• React: Component/style grouping
• Django: Model/view/migration grouping

Creating a Plugin

from smart_commit.plugins import Plugin

class MyPlugin(Plugin):
    name = "MyFramework"
    version = "0.1.0"
    description = "Custom framework support"
    
    def get_ignored_files(self):
        return ["node_modules/**", "venv/**"]
    
    def get_commit_hints(self, file_diffs):
        hints = {}
        for file_diff in file_diffs:
            if "service" in file_diff.file_path:
                hints[file_diff.file_path] = "service"
        return hints

Supported LLM Providers

Smart Commit uses LiteLLM for provider agnostic access:

Provider	Model Format	Example
OpenRouter	anthropic/claude-sonnet	smart-commit run --provider openrouter --model anthropic/claude-sonnet
OpenAI	gpt-4	smart-commit run --provider openai --model gpt-4
Anthropic	claude-sonnet	smart-commit run --provider anthropic --model claude-sonnet
Google	gemini-pro	smart-commit run --provider google --model gemini-pro
Groq	mixtral-8x7b-32768	smart-commit run --provider groq --model mixtral-8x7b-32768
Azure	gpt-4	smart-commit run --provider azure --model gpt-4
Local (Ollama)	llama2	smart-commit run --provider ollama --model llama2

Architecture

Project Structure

smart_commit/
├── __init__.py
├── cli.py                    # Command-line interface
├── config.py                 # Configuration management
├── constants.py              # Constants and enums
├── exceptions.py             # Custom exceptions
├── logger.py                 # Logging setup
├── models.py                 # Data models
├── utils.py                  # Utilities
│
├── git/                      # Git operations
│   ├── scanner.py            # Repository scanning
│   ├── service.py            # Git commands
│   └── safety.py             # Safety checks
│
├── analysis/                 # Code analysis
│   ├── diff_parser.py        # Diff parsing
│   └── summarizer.py         # Summary generation
│
├── embeddings/               # Semantic embeddings
│   ├── generator.py          # Embedding generation
│   └── similarity.py         # Similarity graph
│
├── clustering/               # File clustering
│   ├── semantic.py           # ML-based clustering
│   └── heuristic.py          # Rule-based clustering
│
├── ai/                       # LLM integration
│   ├── client.py             # LiteLLM wrapper
│   └── reviewer.py           # Cluster review
│
├── preview/                  # UI and preview
│   └── renderer.py           # Rich UI rendering
│
├── execution/                # Commit execution
│   └── committer.py          # Commit and sessions
│
└── plugins/                  # Plugin system
    └── base.py               # Plugin base classes

Module Responsibilities

Each module has a single, clear responsibility:

• git/scanner.py - Repository state snapshots
• analysis/diff_parser.py - Structured diff extraction
• analysis/summarizer.py - Concise change summaries
• embeddings/generator.py - Local semantic embeddings
• embeddings/similarity.py - Weighted similarity graph
• clustering/semantic.py - ML-based file grouping
• clustering/heuristic.py - Rule-based fallback
• ai/client.py - Multi-provider LLM access
• ai/reviewer.py - LLM cluster analysis
• preview/renderer.py - Rich terminal UI
• execution/committer.py - Safe commit creation

Development

Setup

git clone https://github.com/hamxa296/Smart-Commit.git
cd Smart-Commit
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

Run Tests

pytest -v
pytest --cov=smart_commit

Format Code

black smart_commit tests
ruff check --fix smart_commit tests

Check Types

mypy smart_commit

Example Workflow

Before Smart Commit

$ git status
On branch main
modified: src/auth/login.ts
modified: src/auth/jwt.ts
modified: src/api/routes.ts
modified: docs/README.md

$ git add src/auth/login.ts
$ git add src/auth/jwt.ts
$ git commit -m "feat(auth): improve login validation"

$ git add src/api/routes.ts
$ git commit -m "fix(api): prevent duplicate requests"

$ git add docs/README.md
$ git commit -m "docs: update README"

# Total time: 15-30 minutes

With Smart Commit

$ smart-commit run

Step 1: Scanning repository...
  ✓ Found 4 changed file(s)
  ✓ +150 additions, -25 deletions
  ✓ Branch: main

Step 2: Analyzing changes...
  ✓ Processed 4 file(s)

Step 3: Grouping related changes...
  ✓ Created 2 commit group(s)

Step 4: AI review...
  ✓ AI review complete

Step 5: Generating commit messages...
  ✓ Generated messages for 2 commit(s)

Step 6: Preview
[Commit 1 preview]
[Commit 2 preview]

Proceed? [y]es [n]o [d]ry-run
y

Step 7: Creating commits...
✓ Success!
  Created 2 commit(s)
    1. abc1234
    2. def5678

# Total time: 30 seconds

Roadmap

• Interactive commit editing
• Learning mode (observes user edits)
• IDE extensions (VS Code, JetBrains)
• Pull request generation
• Changelog generation
• Team configurations
• Analytics dashboard
• GitHub Actions integration
• Semantic history visualization

Contributing

Contributions are welcome! Areas for help:

• Language-specific AST parsers
• Framework plugins (Next.js, FastAPI, etc.)
• IDE extensions
• Documentation
• Testing and bug reports

See CONTRIBUTING.md for guidelines.

License

MIT License - See LICENSE file.

Support

• 📖 Documentation: docs/
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

Acknowledgments

Smart Commit builds on:

• GitPython for git operations
• Typer for CLI
• Rich for terminal UI
• Sentence Transformers for embeddings
• LiteLLM for LLM access
• scikit-learn for clustering

---

Made with ❤️ to make Git history beautiful

Installation

Requirements

• Python 3.12+
• Git

From PyPI (Coming Soon)

pip install smart-commit

From Source

git clone https://github.com/hamxa296/Smart-Commit.git
cd Smart-Commit
pip install -e .

Install Dependencies

pip install -r requirements.txt

Quick Start

Initialize Smart Commit

smart-commit init

Configure Your LLM

smart-commit config --provider openrouter --model anthropic/claude-sonnet --api-key YOUR_KEY

Or set environment variables:

export SMART_COMMIT_PROVIDER=openrouter
export SMART_COMMIT_MODEL=anthropic/claude-sonnet
export SMART_COMMIT_API_KEY=your-api-key

Run Smart Commit

smart-commit run

This will:

1. Detect all changed files
2. Analyze diffs and create summaries
3. Generate semantic embeddings
4. Cluster related files
5. Display a preview of proposed commits
6. Execute commits upon confirmation

Commands

# Analyze and create commits
smart-commit run

# Preview without executing
smart-commit preview

# Undo last session
smart-commit undo

# Configure settings
smart-commit config --show

# Diagnostic checks
smart-commit doctor

# Show version
smart-commit version

# Initialize repository
smart-commit init

Architecture

The tool follows a modular pipeline:

Repository
    ↓
Git Scanner (git_service.py)
    ↓
Diff Parser (diff_parser.py)
    ↓
File Summarizer (summarizer.py)
    ↓
Embedding Generator (embeddings.py)
    ↓
Semantic Clustering (clustering.py)
    ↓
LLM Cluster Review (ai.py)
    ↓
Commit Message Generator (commit_messages.py)
    ↓
Interactive Preview (preview.py)
    ↓
Git Commit Executor (committer.py)

Configuration

Smart Commit looks for configuration in this order:

1. ~/.smart_commit/config.yaml
2. Environment variables (SMART_COMMIT_*)
3. Default values

Example config.yaml

provider: openrouter
model: anthropic/claude-sonnet
embedding_model: all-MiniLM-L6-v2
max_files_per_commit: 8
interactive: true
auto_push: false
conventional_commits: true
use_local_embeddings: true

Supported LLM Providers

Smart Commit uses LiteLLM to support:

• OpenRouter
• OpenAI
• Anthropic
• Gemini
• Groq
• Azure OpenAI
• Local models (Ollama, LM Studio, etc.)

Development

Project Structure

smart_commit/
├── __init__.py
├── cli.py                    # Command-line interface
├── config.py                 # Configuration management
├── models.py                 # Data models
├── utils.py                  # Utility functions
├── git_service.py            # Git operations
├── diff_parser.py            # Diff parsing
├── summarizer.py             # Summary generation
├── embeddings.py             # Embedding generation
├── clustering.py             # File clustering
├── ai.py                     # LLM analysis
├── commit_messages.py        # Message generation
├── preview.py                # Interactive UI
└── committer.py              # Commit execution
tests/
├── __init__.py
├── test_git_service.py
├── test_diff_parser.py
└── test_clustering.py
pyproject.toml
README.md

Development Setup

# Clone the repository
git clone https://github.com/hamxa296/Smart-Commit.git
cd Smart-Commit

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check smart_commit tests
black --check smart_commit tests

# Format code
black smart_commit tests
ruff check --fix smart_commit tests

Milestones

Milestone 1: ✅ Foundation (Complete)

• Repository detection
• Changed file discovery
• Git wrapper
• Deliverable: Basic repository scanner

Milestone 2: In Progress

• Diff parser
• Structured diff representation
• Deliverable: Readable summaries of code changes

Milestone 3: Planned

• Rule-based grouping
• Conventional Commit generation
• Terminal preview
• Deliverable: Working MVP

Milestone 4: Planned

• Embedding generation
• Semantic clustering
• Deliverable: Cross-folder logical commit grouping

Milestone 5: Planned

• LLM cluster refinement
• AI-generated commit messages
• Deliverable: High-quality commit history

Milestone 6: Planned

• Interactive editing
• Undo support
• Session management
• Deliverable: Production-ready CLI

Milestone 7: Planned

• Learning mode
• Plugins
• IDE integration
• PR generation
• PyPI packaging
• Deliverable: Polished, extensible developer tool

Why Smart Commit?

Without Smart Commit

$ git status
modified: src/auth/login.ts
modified: src/api/routes.ts
modified: README.md
modified: src/auth/jwt.ts

$ git add src/auth/login.ts
$ git add src/auth/jwt.ts
$ git commit -m "feat(auth): improve login validation"
# 15 min later...

With Smart Commit

$ smart-commit run
Found 4 changed files

✓ Proposed commits:
  1. feat(auth): improve login validation and session handling
  2. docs: update README

$ [accept] to execute, [e]dit to modify, [s]plit to separate
# 30 seconds later...

Contributing

We welcome contributions! Areas where help is needed:

• Improve diff parsing for different languages
• Add support for more LLM providers
• Implement learning mode for user preferences
• Create IDE extensions (VS Code, JetBrains)
• Optimize clustering algorithm
• Add comprehensive test coverage
• Documentation improvements

See CONTRIBUTING.md for guidelines.

License

MIT License - See LICENSE file for details.

Authors

• Smart Commit Contributors

Support

• 📖 Documentation: See docs/ directory
• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: [e-mail]

Roadmap

• Interactive commit editing
• Learning mode for user preferences
• Framework-specific plugins (React, Django, Next.js, etc.)
• IDE extensions (VS Code, Cursor, Windsurf, JetBrains)
• Pull request generation
• CI/CD integration
• Team mode with shared configurations
• Analytics and insights

---

Made with ❤️ for better Git workflows