🪽 Hermes

AI-powered git commit message generator — powered by local LLMs

Hermes analyzes your staged git changes and generates perfectly formatted conventional commit messages using locally running AI models via Ollama.

---

✨ Features

• 🤖 Local AI — Runs on your machine via Ollama (Mistral/Phi4)
• ⚡ Fast — Smart diff trimming keeps responses quick
• 🎨 Beautiful UI — Rich terminal interface with arrow key selection
• ⏱️ Live Timer — See exactly how long generation takes
• 📝 Conventional Commits — Follows industry-standard format
• 🌍 Global Command — Run hermes from any git repository

---

🚀 Installation

Prerequisites

1. Python 3.12+

   python3 --version

2. Ollama with models installed

   ollama pull gemma4:e4b-it-q4_K_M   # Recommended (9.6GB)
   ollama pull mistral
   ollama pull phi4-mini

3. Clipboard tool (for copy-to-clipboard)

   Ubuntu/Debian

   sudo apt-get install xclip

   macOS

   xclip is built-in

   Windows

   Built-in

Quick Start

# Clone the repository
git clone https://github.com/VarunKvK/hermes-cli.git
cd hermes-cli

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install -e .

# Make it global (Linux/macOS only)
chmod +x hermes.sh
sudo ln -s $(pwd)/hermes.sh /usr/local/bin/hermes

That's it! Now you can run hermes from anywhere.

Install Hermes

git clone https://github.com/VarunKvK/hermes-cli.git
cd hermes-cli
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

Make it globally accessible

chmod +x hermes.sh
sudo ln -s $(pwd)/hermes.sh /usr/local/bin/hermes

---

📖 Usage

# Make some changes in any git repo
cd your-project
git add .

# Run hermes
hermes

Output:

🪽 Hermes — starting...

✓ Analyzing staged changes (0.12s)
✓ Crafting prompt (0.03s)
⠹ Consulting mistral thinking deeply... (8.4s)
✓ Consulting mistral (12.45s)
✓ Parsing commits (0.02s)

╭─────────────────────────────────────────────────╮
│ 🪽 Hermes — AI-generated commit messages        │
╰─────────────────────────────────────────────────╯
┏━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ # ┃ Commit Message                             ┃
┡━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 1 │ feat(auth): add JWT token validation       │
│ 2 │ feat(api): implement user authentication   │
│ 3 │ chore(deps): update security dependencies  │
└───┴────────────────────────────────────────────┘

? Choose a commit message: (Use arrow keys)
 » feat(auth): add JWT token validation
   feat(api): implement user authentication
   chore(deps): update security dependencies
   ❌ Cancel

✅ Selected: feat(auth): add JWT token validation

Copy the message and use it:

git commit -m "feat(auth): add JWT token validation"

---

🤖 Daemon Mode (Auto-Suggestion)

Run Hermes in the background to get automatic suggestions:

hermes --daemon

How it works:

Daemon watches your git repo every 5 seconds
When you stage changes (git add), daemon detects it
Automatically generates commit suggestions
You pick one with arrow keys
If auto_commit: true in config, commits automatically

Perfect for continuous development:

Stage code → get suggestions instantly
No need to manually run hermes
Seamless workflow integration

⚙️ Configuration

Hermes uses Mistral by default. Models are defined in hermes/model.py:

SUPPORTED_MODELS = {
    "mistral": "mistral:latest",
    "phi4": "phi4-mini:latest",
}

DEFAULT_MODEL = "mistral"

---

🛠️ Development

# Install in editable mode
pip install -e .

# Run from source
python main.py

# Run tests (coming in V2)
pytest

---

📝 Conventional Commits Format

Hermes generates messages following the Conventional Commits specification:

type(scope): description

Types:
- feat: New feature
- fix: Bug fix
- docs: Documentation changes
- style: Code style changes (formatting, etc)
- refactor: Code refactoring
- test: Adding tests
- chore: Maintenance tasks

---

🎯 Roadmap

V1.0 ✅

• Local LLM integration via Ollama
• Smart diff analysis
• Beautiful terminal UI
• Arrow key selection
• Global CLI command

V1.1 ✅

• Gemma4 AI model support
• Model selection (--model flag)

V1.2 ✅

• In-place commit editing
• Copy to clipboard
• Questionary integration

V1.3 ✅ (Current)

• Intelligent diff caching (174x speed improvement)
• Cache management (--no-cache, --clear-cache)
• Binary file detection
• Edge case handling
• Business-focused commit scopes
• --all flag for unstaged changes
• Production-grade error handling

V2.0 ✅ (Current)

• Auto-commit feature (--auto-commit/-c)
• Configuration file (~/.hermes/config.json)
• Learn from commit history for personalization
• Daemon mode for real-time suggestions
• Graceful background watching

V3.0 (Future)

• Multiple model comparison
• Custom prompt templates
• Commit message templates library
• Integration with GitHub/GitLab
• Web UI for remote repos

---

📊 Performance Improvements

Caching System

• First run: ~125 seconds (generates + caches)
• Subsequent runs: <1 second (from cache)
• Speed improvement: 174x faster

Model Comparison

• Gemma4 E4B: 78-125s (recommended)
• Mistral 7.2B: 112-235s
• Phi4-mini: Similar to Mistral

Gemma4 is 30% faster with better reasoning.

---

🤝 Contributing

Contributions are welcome! This is a learning project built to explore:

• Agentic AI development
• Local LLM integration
• Production-quality Python CLIs
• Terminal UI/UX best practices

---

📄 License

MIT License - feel free to use and modify

---

🙏 Acknowledgments

• Built with Ollama
• UI powered by Rich
• Inspired by Greek mythology — Hermes, messenger of the gods

---

Made with ⚡ by VarunKvK