smart-commit-cli 0.2.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