ikomet 0.1.2

AI-powered Conventional Commit message generator using your staged changes

🚀 Komet

AI-Powered Conventional Commit Message Generator

Komet is a smart CLI tool that leverages Groq's LLM API to automatically generate professional, Conventional Commits formatted commit messages from your staged git changes. Say goodbye to bland commit messages and hello to consistent, meaningful version control history.

---

✨ Features

• 🤖 AI-Powered Analysis: Uses Groq's fast LLM (Llama 3.3 70B) to understand your code changes
• 📝 Conventional Commits: Automatically follows industry-standard commit message format
• ⚡ Lightning Fast: Groq's infrastructure provides near-instant responses
• 🎯 Context-Aware: Analyzes actual git diffs to generate accurate, meaningful messages
• 🛡️ Safe & Smart: Truncates large diffs, validates git repos, and handles edge cases gracefully
• 🎨 Beautiful CLI: Built with Typer for a modern, user-friendly command-line experience

---

🎬 Demo

# Stage your changes
$ git add src/komet/main.py

# Let Komet generate the commit message
$ komet

Suggested commit message:

feat(main): add automatic diff truncation for large changesets

Use it like this:
  git commit -m 'feat(main): add automatic diff truncation for large changesets'

---

🚀 Installation

Prerequisites

• Python 3.10 or higher
• Git repository
• Groq API key (Get it here)

Quick Install from PyPI (Recommended)

Install globally using pipx (recommended for CLI tools):

# Install pipx if you don't have it
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Install ikomet
pipx install ikomet

# Now use it anywhere!
komet

Or install with pip:

pip install ikomet

Install from Source

For development or contributing:

# Clone the repository
git clone https://github.com/ajabrii/Komet.git
cd Komet

# Install with poetry
poetry install

# Run Komet
poetry run komet

---

📖 Usage

Basic Workflow

1. Stage your changes as usual:

   git add <files>
   

2. Run Komet:

   komet
   

3. Copy and commit with the suggested message:

Set it up once:

# Linux/macOS - Temporary (current session only)
export GROQ_API_KEY=gq_xxxxxxxxxxxxxxxx

# Linux/macOS - Permanent (add to ~/.bashrc, ~/.zshrc, or ~/.profile)
echo 'export GROQ_API_KEY=gq_xxxxxxxxxxxxxxxx' >> ~/.bashrc
source ~/.bashrc

# Windows (PowerShell)
$env:GROQ_API_KEY="gq_xxxxxxxxxxxxxxxx"

# Windows - Permanent (System Environment Variables)
setx GROQ_API_KEY "gq_xxxxxxxxxxxxxxxx"
# Temporary (current session only)
export GROQ_API_KEY=gq_xxxxxxxxxxxxxxxx

# Permanent (add to ~/.bashrc, ~/.zshrc, or ~/.profile)
echo 'export GROQ_API_KEY=gq_xxxxxxxxxxxxxxxx' >> ~/.bashrc
source ~/.bashrc

---

🏗️ How It Works

1. Git Diff Extraction: Komet uses GitPython to read your staged changes (git diff --cached)
2. Context Preparation: The diff is sent to Groq's LLM with a carefully crafted system prompt
3. AI Analysis: The LLM analyzes the code changes and generates a Conventional Commit message
4. Formatted Output: The result is displayed with usage instructions

Conventional Commit Format

Komet generates messages following this structure:

<type>(<optional-scope>): <short-description>

<optional-body>

<optional-footer>

Supported types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

---

🛠️ Technology Stack

Technology	Purpose
Python 3.10+	Core programming language
Poetry	Dependency management and packaging
Typer	Modern CLI framework with beautiful output
GitPython	Git repository interaction
Groq SDK	LLM API integration (Llama 3.3 70B)

---

📁 Project Structure

Komet/
├── src/
│   └── komet/
│       ├── __init__.py          # Package initialization
│       └── main.py              # Core application logic
├── pyproject.toml               # Poetry configuration & dependencies
└── README.md                    # Project documentation

---

🔧 Configuration

Model Selection

Komet uses llama-3.3-70b-versatile by default. You can modify main.py to use other Groq models:

• llama-3.3-70b-versatile - Best quality & speed balance (default)
• mixtral-8x7b-32768 - Cheaper alternative, still excellent quality

Diff Size Limits

Large diffs are automatically truncated to 15,000 characters to fit within LLM context windows. Adjust in main.py.

---

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📝 License

This project is open source and available under the MIT License.

---

👤 Author

Abdelali Jabri

• LinkedIn: Linkedin
• GitHub: @ajabrii
• Email: [e-mail]

---

🙏 Acknowledgments

• Conventional Commits - For the commit message specification
• Groq - For providing lightning-fast LLM inference
• Typer - For the excellent CLI framework

---

🌟 Why Komet?

In professional software development, clear commit history is crucial for:

• Code Reviews: Understanding what changed and why
• Debugging: Using git bisect to find when bugs were introduced
• Documentation: Auto-generating changelogs from commits
• Team Collaboration: Maintaining consistency across team members

Komet automates best practices, ensuring every commit tells a clear story.

---

Made with ❤️ by Abdelali Jabri