# 🤖 AI-Powered Git Commit Message Generator
[](https://badge.fury.io/py/ai-commit-generator)
[](https://pypi.org/project/ai-commit-generator/)
[](https://opensource.org/licenses/MIT)
[](https://pepy.tech/project/ai-commit-generator)
**Automatically generate conventional commit messages using AI - No backend/frontend required!**
This tool works as a **Git pre-commit hook** that analyzes your staged changes and generates professional commit messages using AI APIs (Groq, OpenRouter, Cohere).
---
## 🚀 Quick Start (2 minutes)
### 1. Install the Package
```bash
# Install from PyPI (recommended)
pip install ai-commit-generator
# Or install from source
pip install git+https://github.com/your-org/ai-commit-generator.git
```
### 2. Get API Key (Free)
- **Groq** (Recommended): https://console.groq.com/keys
- **OpenRouter**: https://openrouter.ai/keys
- **Cohere**: https://dashboard.cohere.ai/api-keys
### 3. Install in Your Project
```bash
# Go to your project
cd /path/to/your/project
# Install the Git hook
ai-commit-generator install
# Add your API key
echo "GROQ_API_KEY=your_key_here" >> .env
```
### 4. Use It
```bash
# Normal Git workflow - AI handles the message!
git add src/components/Button.js
git commit # ✨ AI generates: "feat(ui): add Button component with hover effects"
```
---
## 📦 Installation Methods
### Method 1: PyPI (Recommended)
```bash
pip install ai-commit-generator
```
### Method 2: From Source
```bash
git clone https://github.com/your-org/ai-commit-generator.git
cd ai-commit-generator
pip install -e .
```
### Method 3: Legacy Bash Script
For the original bash-based installation, see [LEGACY.md](LEGACY.md).
---
## ✨ Features
- **🤖 AI-Powered**: Uses Groq, OpenRouter, or Cohere APIs
- **📝 Conventional Commits**: Automatic `type(scope): description` format
- **⚡ Fast**: < 2 second response time with Groq
- **🔧 Configurable**: Customize prompts, models, and scopes
- **🛡️ Secure**: Only staged changes sent to AI, no data storage
- **🔄 Fallback**: Works even if AI fails
- **🐍 Python Package**: Easy installation and distribution
- **🧪 Testable**: Comprehensive test suite and type hints
- **🎨 Rich CLI**: Beautiful command-line interface with colors
---
## 🎯 Example Output
**Before:**
```bash
git commit -m "fix"
git commit -m "update"
git commit -m "changes"
```
**After:**
```bash
feat(auth): implement JWT token refresh mechanism
fix(api): resolve race condition in user registration
docs: update README with installation instructions
refactor(utils): optimize date formatting functions
```
---
## 📁 Project Structure
```
ai-commit-generator/
├── README.md # This file
├── TEAM_SETUP_GUIDE.md # Detailed team documentation
├── pyproject.toml # Python package configuration
├── src/
│ └── ai_commit_generator/
│ ├── __init__.py # Package initialization
│ ├── cli.py # Command-line interface
│ ├── core.py # Main commit generation logic
│ ├── config.py # Configuration management
│ ├── api_clients.py # AI API clients
│ └── git_hook.py # Git hook management
├── templates/
│ ├── .commitgen.yml # Configuration template
│ └── .env.example # Environment template
├── tests/ # Test suite
├── examples/ # Usage examples
└── legacy/ # Original bash scripts
├── install_hook.sh # Legacy installer
└── hooks/
└── prepare-commit-msg # Legacy hook script
```
---
## 🖥️ CLI Commands
### Install Hook
```bash
# Install Git hook in current repository
ai-commit-generator install
# Install with configuration files
ai-commit-generator install --config
# Force overwrite existing hook
ai-commit-generator install --force
```
### Manage Installation
```bash
# Check installation status
ai-commit-generator status
# Test with current staged changes
ai-commit-generator test
# Uninstall hook
ai-commit-generator uninstall
```
### Generate Messages
```bash
# Generate message for staged changes
ai-commit-generator generate
# Generate without writing to file (dry run)
ai-commit-generator generate --dry-run
# Generate and save to specific file
ai-commit-generator generate --output commit-msg.txt
```
### Configuration
```bash
# Show current configuration
ai-commit-generator config --show
# Validate configuration
ai-commit-generator config --validate
```
---
## 🔧 Configuration
### Basic Setup (`.env`)
```bash
# Choose one provider
GROQ_API_KEY=gsk_your_key_here
# OPENROUTER_API_KEY=sk-or-your_key_here
# COHERE_API_KEY=your_cohere_key_here
```
### Advanced Setup (`.commitgen.yml`)
```yaml
api:
provider: groq
commit:
max_chars: 72
types: [feat, fix, docs, style, refactor, test, chore]
scopes: [api, ui, auth, db, config]
prompt:
template: |
Generate a conventional commit message for:
{{diff}}
```
---
## 🏢 Team Deployment
### Option 1: Shared Network Drive
```bash
# Copy to shared location
cp -r ai-commit-generator /shared/tools/
# Team members install from shared location
/shared/tools/ai-commit-generator/install_hook.sh
```
### Option 2: Internal Git Repository
```bash
# Create internal repo
git init ai-commit-generator
git add .
git commit -m "feat: add AI commit message generator"
git remote add origin https://github.com/your-org/ai-commit-generator.git
git push -u origin main
# Team members clone and install
git clone https://github.com/your-org/ai-commit-generator.git
cd your-project
../ai-commit-generator/install_hook.sh
```
### Option 3: Package Distribution
```bash
# Create distributable package
tar -czf ai-commit-generator.tar.gz ai-commit-generator/
# Team members download and extract
curl -sSL https://your-server/ai-commit-generator.tar.gz | tar -xz
./ai-commit-generator/install_hook.sh
```
---
## 🛠️ Advanced Usage
### Custom Prompts
```yaml
prompt:
template: |
You are a senior developer. Generate a commit message for:
{{diff}}
Requirements:
- Use conventional commits
- Be specific about business impact
- Maximum {{max_chars}} characters
```
### Multiple Models
```bash
# Fast and efficient
GROQ_MODEL=llama3-8b-8192
# More detailed
GROQ_MODEL=llama3-70b-8192
# Creative
GROQ_MODEL=mixtral-8x7b-32768
```
### Debug Mode
```bash
DEBUG_ENABLED=true
tail -f .commitgen.log
```
---
## 🚨 Troubleshooting
| Issue | Solution |
|-------|----------|
| "API key not found" | Check `.env` file, ensure correct variable is set |
| "jq: command not found" | Install jq: `brew install jq` or `apt install jq` |
| "Rate limit exceeded" | Wait 1 minute or switch to different provider |
| "Hook not working" | Reinstall: `./install_hook.sh` |
---
## 📊 Provider Comparison
| Provider | Speed | Cost | Models | Best For |
|----------|-------|------|--------|----------|
| **Groq** | ⚡ Very Fast | 🆓 Free | Llama 3, Mixtral | Teams, Daily Use |
| **OpenRouter** | 🐌 Medium | 💰 Paid | Claude, GPT-4 | Premium Quality |
| **Cohere** | ⚖️ Fast | 🆓 Free Tier | Command-R | Enterprise |
---
## 🤝 Contributing
1. Fork the repository
2. Create feature branch: `git checkout -b feature/amazing-feature`
3. Commit changes: `git commit -m 'feat: add amazing feature'`
4. Push to branch: `git push origin feature/amazing-feature`
5. Open Pull Request
---
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
---
## 🙏 Acknowledgments
- [Conventional Commits](https://www.conventionalcommits.org/) specification
- [Groq](https://groq.com/) for fast AI inference
- [OpenRouter](https://openrouter.ai/) for model diversity
- [Cohere](https://cohere.ai/) for enterprise AI
---
**Transform your team's commit messages today! 🚀**
Raw data
{
"_id": null,
"home_page": null,
"name": "joshi-ai-commits",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "git, commit, ai, conventional-commits, automation, groq, openrouter, cohere, llama, claude, gpt, developer-tools, productivity, git-hooks, commit-messages, machine-learning, natural-language-processing, cli",
"author": null,
"author_email": "Joshi <joshi@nuox.io>",
"download_url": "https://files.pythonhosted.org/packages/e2/25/061885c4e3c99e005348d0e6527453c7d026a83ea2054bfa1519d6183da2/joshi_ai_commits-1.0.0.tar.gz",
"platform": null,
"description": "# \ud83e\udd16 AI-Powered Git Commit Message Generator\n\n[](https://badge.fury.io/py/ai-commit-generator)\n[](https://pypi.org/project/ai-commit-generator/)\n[](https://opensource.org/licenses/MIT)\n[](https://pepy.tech/project/ai-commit-generator)\n\n**Automatically generate conventional commit messages using AI - No backend/frontend required!**\n\nThis tool works as a **Git pre-commit hook** that analyzes your staged changes and generates professional commit messages using AI APIs (Groq, OpenRouter, Cohere).\n\n---\n\n## \ud83d\ude80 Quick Start (2 minutes)\n\n### 1. Install the Package\n```bash\n# Install from PyPI (recommended)\npip install ai-commit-generator\n\n# Or install from source\npip install git+https://github.com/your-org/ai-commit-generator.git\n```\n\n### 2. Get API Key (Free)\n- **Groq** (Recommended): https://console.groq.com/keys\n- **OpenRouter**: https://openrouter.ai/keys\n- **Cohere**: https://dashboard.cohere.ai/api-keys\n\n### 3. Install in Your Project\n```bash\n# Go to your project\ncd /path/to/your/project\n\n# Install the Git hook\nai-commit-generator install\n\n# Add your API key\necho \"GROQ_API_KEY=your_key_here\" >> .env\n```\n\n### 4. Use It\n```bash\n# Normal Git workflow - AI handles the message!\ngit add src/components/Button.js\ngit commit # \u2728 AI generates: \"feat(ui): add Button component with hover effects\"\n```\n\n---\n\n## \ud83d\udce6 Installation Methods\n\n### Method 1: PyPI (Recommended)\n```bash\npip install ai-commit-generator\n```\n\n### Method 2: From Source\n```bash\ngit clone https://github.com/your-org/ai-commit-generator.git\ncd ai-commit-generator\npip install -e .\n```\n\n### Method 3: Legacy Bash Script\nFor the original bash-based installation, see [LEGACY.md](LEGACY.md).\n\n---\n\n## \u2728 Features\n\n- **\ud83e\udd16 AI-Powered**: Uses Groq, OpenRouter, or Cohere APIs\n- **\ud83d\udcdd Conventional Commits**: Automatic `type(scope): description` format\n- **\u26a1 Fast**: < 2 second response time with Groq\n- **\ud83d\udd27 Configurable**: Customize prompts, models, and scopes\n- **\ud83d\udee1\ufe0f Secure**: Only staged changes sent to AI, no data storage\n- **\ud83d\udd04 Fallback**: Works even if AI fails\n- **\ud83d\udc0d Python Package**: Easy installation and distribution\n- **\ud83e\uddea Testable**: Comprehensive test suite and type hints\n- **\ud83c\udfa8 Rich CLI**: Beautiful command-line interface with colors\n\n---\n\n## \ud83c\udfaf Example Output\n\n**Before:**\n```bash\ngit commit -m \"fix\"\ngit commit -m \"update\"\ngit commit -m \"changes\"\n```\n\n**After:**\n```bash\nfeat(auth): implement JWT token refresh mechanism\nfix(api): resolve race condition in user registration \ndocs: update README with installation instructions\nrefactor(utils): optimize date formatting functions\n```\n\n---\n\n## \ud83d\udcc1 Project Structure\n\n```\nai-commit-generator/\n\u251c\u2500\u2500 README.md # This file\n\u251c\u2500\u2500 TEAM_SETUP_GUIDE.md # Detailed team documentation\n\u251c\u2500\u2500 pyproject.toml # Python package configuration\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 ai_commit_generator/\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\n\u2502 \u251c\u2500\u2500 cli.py # Command-line interface\n\u2502 \u251c\u2500\u2500 core.py # Main commit generation logic\n\u2502 \u251c\u2500\u2500 config.py # Configuration management\n\u2502 \u251c\u2500\u2500 api_clients.py # AI API clients\n\u2502 \u2514\u2500\u2500 git_hook.py # Git hook management\n\u251c\u2500\u2500 templates/\n\u2502 \u251c\u2500\u2500 .commitgen.yml # Configuration template\n\u2502 \u2514\u2500\u2500 .env.example # Environment template\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 examples/ # Usage examples\n\u2514\u2500\u2500 legacy/ # Original bash scripts\n \u251c\u2500\u2500 install_hook.sh # Legacy installer\n \u2514\u2500\u2500 hooks/\n \u2514\u2500\u2500 prepare-commit-msg # Legacy hook script\n```\n\n---\n\n## \ud83d\udda5\ufe0f CLI Commands\n\n### Install Hook\n```bash\n# Install Git hook in current repository\nai-commit-generator install\n\n# Install with configuration files\nai-commit-generator install --config\n\n# Force overwrite existing hook\nai-commit-generator install --force\n```\n\n### Manage Installation\n```bash\n# Check installation status\nai-commit-generator status\n\n# Test with current staged changes\nai-commit-generator test\n\n# Uninstall hook\nai-commit-generator uninstall\n```\n\n### Generate Messages\n```bash\n# Generate message for staged changes\nai-commit-generator generate\n\n# Generate without writing to file (dry run)\nai-commit-generator generate --dry-run\n\n# Generate and save to specific file\nai-commit-generator generate --output commit-msg.txt\n```\n\n### Configuration\n```bash\n# Show current configuration\nai-commit-generator config --show\n\n# Validate configuration\nai-commit-generator config --validate\n```\n\n---\n\n## \ud83d\udd27 Configuration\n\n### Basic Setup (`.env`)\n```bash\n# Choose one provider\nGROQ_API_KEY=gsk_your_key_here\n# OPENROUTER_API_KEY=sk-or-your_key_here\n# COHERE_API_KEY=your_cohere_key_here\n```\n\n### Advanced Setup (`.commitgen.yml`)\n```yaml\napi:\n provider: groq\n \ncommit:\n max_chars: 72\n types: [feat, fix, docs, style, refactor, test, chore]\n scopes: [api, ui, auth, db, config]\n \nprompt:\n template: |\n Generate a conventional commit message for:\n {{diff}}\n```\n\n---\n\n## \ud83c\udfe2 Team Deployment\n\n### Option 1: Shared Network Drive\n```bash\n# Copy to shared location\ncp -r ai-commit-generator /shared/tools/\n\n# Team members install from shared location\n/shared/tools/ai-commit-generator/install_hook.sh\n```\n\n### Option 2: Internal Git Repository\n```bash\n# Create internal repo\ngit init ai-commit-generator\ngit add .\ngit commit -m \"feat: add AI commit message generator\"\ngit remote add origin https://github.com/your-org/ai-commit-generator.git\ngit push -u origin main\n\n# Team members clone and install\ngit clone https://github.com/your-org/ai-commit-generator.git\ncd your-project\n../ai-commit-generator/install_hook.sh\n```\n\n### Option 3: Package Distribution\n```bash\n# Create distributable package\ntar -czf ai-commit-generator.tar.gz ai-commit-generator/\n\n# Team members download and extract\ncurl -sSL https://your-server/ai-commit-generator.tar.gz | tar -xz\n./ai-commit-generator/install_hook.sh\n```\n\n---\n\n## \ud83d\udee0\ufe0f Advanced Usage\n\n### Custom Prompts\n```yaml\nprompt:\n template: |\n You are a senior developer. Generate a commit message for:\n \n {{diff}}\n \n Requirements:\n - Use conventional commits\n - Be specific about business impact\n - Maximum {{max_chars}} characters\n```\n\n### Multiple Models\n```bash\n# Fast and efficient\nGROQ_MODEL=llama3-8b-8192\n\n# More detailed\nGROQ_MODEL=llama3-70b-8192\n\n# Creative\nGROQ_MODEL=mixtral-8x7b-32768\n```\n\n### Debug Mode\n```bash\nDEBUG_ENABLED=true\ntail -f .commitgen.log\n```\n\n---\n\n## \ud83d\udea8 Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| \"API key not found\" | Check `.env` file, ensure correct variable is set |\n| \"jq: command not found\" | Install jq: `brew install jq` or `apt install jq` |\n| \"Rate limit exceeded\" | Wait 1 minute or switch to different provider |\n| \"Hook not working\" | Reinstall: `./install_hook.sh` |\n\n---\n\n## \ud83d\udcca Provider Comparison\n\n| Provider | Speed | Cost | Models | Best For |\n|----------|-------|------|--------|----------|\n| **Groq** | \u26a1 Very Fast | \ud83c\udd93 Free | Llama 3, Mixtral | Teams, Daily Use |\n| **OpenRouter** | \ud83d\udc0c Medium | \ud83d\udcb0 Paid | Claude, GPT-4 | Premium Quality |\n| **Cohere** | \u2696\ufe0f Fast | \ud83c\udd93 Free Tier | Command-R | Enterprise |\n\n---\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repository\n2. Create feature branch: `git checkout -b feature/amazing-feature`\n3. Commit changes: `git commit -m 'feat: add amazing feature'`\n4. Push to branch: `git push origin feature/amazing-feature`\n5. Open Pull Request\n\n---\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n## \ud83d\ude4f Acknowledgments\n\n- [Conventional Commits](https://www.conventionalcommits.org/) specification\n- [Groq](https://groq.com/) for fast AI inference\n- [OpenRouter](https://openrouter.ai/) for model diversity\n- [Cohere](https://cohere.ai/) for enterprise AI\n\n---\n\n**Transform your team's commit messages today! \ud83d\ude80**\n",
"bugtrack_url": null,
"license": null,
"summary": "AI-powered Git commit message generator that automatically creates conventional commit messages using Groq, OpenRouter, or Cohere APIs",
"version": "1.0.0",
"project_urls": {
"Bug Reports": "https://github.com/Joshi-e8/ai-commit-generator/issues",
"Changelog": "https://github.com/Joshi-e8/ai-commit-generator/releases",
"Documentation": "https://github.com/Joshi-e8/ai-commit-generator#readme",
"Feature Requests": "https://github.com/Joshi-e8/ai-commit-generator/issues",
"Homepage": "https://github.com/Joshi-e8/ai-commit-generator",
"Issues": "https://github.com/Joshi-e8/ai-commit-generator/issues",
"Repository": "https://github.com/Joshi-e8/ai-commit-generator.git",
"Source Code": "https://github.com/Joshi-e8/ai-commit-generator"
},
"split_keywords": [
"git",
" commit",
" ai",
" conventional-commits",
" automation",
" groq",
" openrouter",
" cohere",
" llama",
" claude",
" gpt",
" developer-tools",
" productivity",
" git-hooks",
" commit-messages",
" machine-learning",
" natural-language-processing",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6a5bb5e377445b1486739a44e76c09a62b509c516b531b61ff298cc97ccdb78a",
"md5": "82b7762aaa1ec4f7afcf94f81d9daa37",
"sha256": "8ef3fe17c174d7a729fb2004dc769d5920e56d0f8dd9944afebc6f4130a86a9f"
},
"downloads": -1,
"filename": "joshi_ai_commits-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "82b7762aaa1ec4f7afcf94f81d9daa37",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 21046,
"upload_time": "2025-07-17T06:49:03",
"upload_time_iso_8601": "2025-07-17T06:49:03.368384Z",
"url": "https://files.pythonhosted.org/packages/6a/5b/b5e377445b1486739a44e76c09a62b509c516b531b61ff298cc97ccdb78a/joshi_ai_commits-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e225061885c4e3c99e005348d0e6527453c7d026a83ea2054bfa1519d6183da2",
"md5": "e2d8871b968971e2851508e0576004c9",
"sha256": "95200fda45620a571d8b12b638adcfa118051b2d593dfa1f2313245f4a16f8ff"
},
"downloads": -1,
"filename": "joshi_ai_commits-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "e2d8871b968971e2851508e0576004c9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 22983,
"upload_time": "2025-07-17T06:49:04",
"upload_time_iso_8601": "2025-07-17T06:49:04.890048Z",
"url": "https://files.pythonhosted.org/packages/e2/25/061885c4e3c99e005348d0e6527453c7d026a83ea2054bfa1519d6183da2/joshi_ai_commits-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 06:49:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Joshi-e8",
"github_project": "ai-commit-generator",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "joshi-ai-commits"
}
JSON
