Built with the tools and technologies:
# Option 1: Homebrew (Recommended)
brew tap joaquinalmora/tap
brew install commitgen
# Option 2: Go Install
go install github.com/joaquinalmora/commitgen/cmd/commitgen@latest
# Option 3: From Source
git clone https://github.com/joaquinalmora/commitgen.git
cd commitgen && make build && make install# Interactive configuration (recommended)
commitgen init
# Add your OpenAI API key when prompted
# Then install git hooks and shell integration
commitgen install-hook
commitgen install-shell# Stage your changes
git add .
# Generate AI-powered commit message
commitgen suggest --ai
# Or just commit and get auto-suggestions
git commit -m "" # AI suggestions appear here- AI-Powered: OpenAI GPT-4o-mini (and other OpenAI models) for professional commit messages
- Auto-Cache: Intelligent caching with 50x performance boost
- Git Integration: Automatic hooks for seamless workflow
- Shell Integration: Ghost text suggestions as you type
git commit -m " - Smart Fallback: Heuristic generation when AI is unavailable
- Zero Config: One-command setup with intelligent defaults
- Context-Aware: Analyzes actual code changes, not just file names
| Variable | Purpose | Default |
|---|---|---|
OPENAI_API_KEY |
API key used by the OpenAI provider | required for AI |
COMMITGEN_AI |
Enable AI automatically (otherwise pass --ai) |
false |
COMMITGEN_MODEL |
OpenAI model name | gpt-4o-mini |
COMMITGEN_BASE_URL |
Override the OpenAI API URL for proxies/self-hosting | https://api.openai.com/v1 |
COMMITGEN_MAX_FILES |
Max staged files included in the prompt | 10 |
COMMITGEN_PATCH_BYTES |
Max bytes of diff sent to the AI | 102400 |
COMMITGEN_AI_FALLBACK |
Disable (false) or enable (true) heuristic fallback |
true |
COMMITGEN_CONVENTIONS_FILE |
Path to custom commit-style markdown | unset |
Create commitgen.yaml:
ai:
enabled: true
provider: "openai"
model: "gpt-4o-mini"
api_key: "" # Use environment variable
performance:
patch_bytes: 4000
cache_ttl: "24h"
max_files: 10
output:
verbose: false
colors: truecommitgen suggest # Generate commit message
commitgen suggest --ai # Force AI generation
commitgen suggest --cached # Reuse the last cached AI result
commitgen suggest --verbose # Show detailed logs
commitgen cached --plain # Print cached message without formatting
commitgen cache # Pre-generate cache
commitgen cache --clear # Clear cache
commitgen init # Interactive config (local)
commitgen init --global # Interactive config in ~/.commitgen.yaml
commitgen env-example # Write .env.example
commitgen doctor # System health check
commitgen version --verbose # Include git commit + build date| Command | What it does | Helpful flags |
|---|---|---|
commitgen suggest |
Generates commit text from staged changes | --ai, --cached, --plain, --verbose |
commitgen cache |
Performs AI/heuristic generation and stores the result | --clear, --verbose |
commitgen cached |
Prints the most recent cached commit message (used by hooks/shell) | --plain, --verbose |
commitgen install-hook / uninstall-hook |
Manage .git/hooks/prepare-commit-msg and .git/hooks/post-index-change |
n/a |
commitgen install-shell / uninstall-shell |
Manage the guarded ~/.zshrc block + ~/.config/commitgen.zsh snippet |
n/a |
commitgen init |
Interactive YAML config generator (supports --global) |
--global |
commitgen env-example |
Writes .env.example with the current defaults |
n/a |
commitgen doctor |
Runs environment checks | --verbose (via COMMITGEN_AI=1 etc.) |
commitgen version |
Prints version/build metadata | --verbose |
# Install git hooks for auto-suggestions
commitgen install-hook
# Now git commit will auto-suggest messages
git commit
# Message: "feat: add user authentication with JWT tokens"
# Uninstall hooks
commitgen uninstall-hook
commitgen install-hookwrites both.git/hooks/prepare-commit-msg(inserts the suggestion when the message is empty) and.git/hooks/post-index-change(warms the cache every time you rungit add). The cache-first behavior depends oncommitgen cached, so keep the binary accessible to your repo.post-index-changeis new in Git 2.44, so skip the auto-cache hook (or remove it viacommitgen uninstall-hook) if you are on an older Git release or a hosting platform that disallows it.
Shell ghost text currently targets zsh only. The installer writes a guarded block to ~/.zshrc that sources ~/.config/commitgen.zsh, which contains the preview widget and ^F binding.
# Install shell integration (zsh)
commitgen install-shell
# Now typing 'git commit -m "' will show ghost text suggestions
git commit -m "feat: add user auth and↩ # <-- AI suggestion appearsThe installer leaves any existing ~/.zshrc content alone, and you can remove the snippet at any time with commitgen uninstall-shell (which deletes both the guard block and ~/.config/commitgen.zsh).
OpenAI is the only wired-up provider today. Local/Ollama support is still being designed, so the CLI will ignore COMMITGEN_PROVIDER=ollama (or similar) until the provider package grows that implementation.
| Provider | Status | Setup |
|---|---|---|
| OpenAI | ✅ Supported | export OPENAI_API_KEY=sk-... then choose a model with COMMITGEN_MODEL |
| Local/Ollama | 🔜 Planned | Not implemented yet (follow project updates) |
- Get API key from OpenAI Platform
- Set environment variable:
export OPENAI_API_KEY=sk-your-key - Optional: Choose model:
export COMMITGEN_MODEL=gpt-4o-mini
Ollama/local-hosted models are high on the roadmap, but the provider code does not talk to Ollama yet. Track the repo releases for updates if you need on-device inference.
"No API key" error:
- Run
commitgen initfor interactive setup - Set
OPENAI_API_KEYenvironment variable - Verify API key at OpenAI platform
"Not a git repository" error:
- Ensure you're in a git repository (
git initif needed) - Check current directory with
pwd
"No staged changes" error:
- Stage files first:
git add <files> - Check status:
git status
Shell integration not working:
- Run
commitgen doctorfor diagnostics - Reinstall:
commitgen uninstall-shell && commitgen install-shell - Source shell:
source ~/.zshrc
commitgen suggest --verbose # Show detailed logs
commitgen doctor # System diagnostics- Analyze Changes: Reads git staged changes and file modifications
- Generate Context: Creates intelligent prompts from code diffs
- AI Processing: Sends context to the OpenAI provider
- Smart Caching: Caches results for identical changes
- Integration: Provides suggestions via git hooks or shell integration
- Setup Guide - Complete installation and configuration
- AI Commit Workflow - zsh
aicommitfunction + sample git hook
Technical, contributing, and changelog docs are on the roadmap—follow the repo releases if you need those references.
scripts/test-ai.sh— sanity-checks the OpenAI flow using the same env vars as the app (OPENAI_API_KEY,COMMITGEN_MODEL, etc.).scripts/export-conventions.sh— placeholder for a future conventions exporter (currently a no-op script).scripts/setup-company-conventions.sh— placeholder for company-specific conventions bootstrap (currently a no-op script).
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make changes with tests
- Submit a pull request
Detailed contribution guidelines are on the roadmap—feel free to open a PR or issue if you need additional context.
Complete removal:
# Remove integrations
commitgen uninstall-shell
commitgen uninstall-hook # Run in each repository
# Remove binary (if installed manually)
sudo rm /usr/local/bin/commitgen
# Or via Homebrew
brew uninstall commitgen
# Clean up configuration
rm ~/.env ~/.config/commitgen.zshMIT License - see LICENSE file for details.