CommitGen - AI-Powered Git Commit Message Generator

A standalone CLI tool that generates conventional commit messages using AI. Commitgen analyzes your git changes and creates descriptive, properly formatted commit messages automatically.

Table of Contents

• Features
• Installation
  • From Source
  • Quick Install
• Usage
  • Basic Usage
  • Using Different AI Providers
  • Examples
• Provider Management
  • List Providers
  • Set Default Provider
  • Add Custom Provider
  • Remove Provider
• Configuration
• Output Format
• Development
  • Building
  • Testing
  • Installation for Development
• Advanced Usage
  • Custom Git Diff Analysis
  • Troubleshooting
  • Integration with Git Hooks
• Contributing
• Requirements
• License

Features

• Multiple Analysis Modes: Staged files, all changes, or untracked files
• Conventional Commits: Follows type(scope): description format
• Smart Scope Detection: Automatically extracts service/module from file paths
• Flexible AI Providers: Built-in support for Claude, Gemini, Copilot, OpenCode, Kilo, Cursor, Aider, and more
• Custom Providers: Add any AI CLI tool as a provider
• Interactive: Preview and confirm commit messages before committing

Installation

📦 npm Installation

Node.js Package Manager

npm install -g @freepik/commitgen

pnpm

pnpm install -g @freepik/commitgen

yarn

yarn global add @freepik/commitgen

Usage

Basic Usage

# Generate commit message from staged files (default)
commitgen

# Or explicitly
commitgen commit staged
commitgen commit s

# Generate from all changes (stages + commits)
commitgen commit all
commitgen commit a

# Generate from untracked files only
commitgen commit untracked
commitgen commit u

Using Different AI Providers

# Use Claude (default)
commitgen
commitgen --provider claude

# Use Gemini
commitgen --provider gemini

# Use Copilot
commitgen --provider copilot

# Use OpenCode
commitgen --provider opencode

# Use provider with specific subcommand
commitgen commit staged --provider gemini
commitgen commit all --provider copilot

# Use Kilo
commitgen --provider kilo

# Use Cursor
commitgen --provider cursor

Provider Management

List Providers

commitgen provider list

Output:

Available providers:
  * claude: claude
    gemini: gemini
    copilot: copilot
    opencode: opencode run
    kilo: kilo
    cursor: cursor-agent
    aider: aider

  * = default provider

Config file: ~/.commitgen/config.json

Set Default Provider

commitgen provider default kilo

Add Custom Provider

Add any AI CLI tool as a provider:

# Basic provider
commitgen provider add myai --command myai-cli

# Provider with arguments
commitgen provider add custom-ai --command custom-ai --args="--non-interactive" --args="--model=gpt-4"

Remove Provider

commitgen provider remove myai

Configuration

Commitgen uses your existing AI CLI commands and configuration. Make sure you have:

1. AI CLI commands available in your PATH (built-in support for):
   • claude for Claude
   • gemini for Gemini
   • copilot for Copilot
   • opencode for OpenCode
   • kilo for Kilo
   • cursor-agent for Cursor
   • aider for Aider
   • continue for Continue
   • codeium for Codeium
2. Proper API keys configured for your chosen AI provider
3. Git repository initialized

Config File

Configuration is stored in ~/.commitgen/config.json:

{
  "defaultProvider": "claude",
  "providers": {
    "my-custom-ai": {
      "command": "my-ai-cli",
      "args": ["--non-interactive"]
    }
  }
}

Output Format

Commitgen generates conventional commit messages following this format:

type(scope): description

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, etc.)
• refactor: Code refactoring
• test: Test additions/changes
• chore: Maintenance tasks

Examples:

• feat(service:rating): add get RestaurantQuickReview with caching
• fix(api:user): resolve null pointer in validation
• docs(readme): update setup instructions

Development

Building

go build -o commitgen main.go

Testing

go test ./...

Installation for Development

go build -o commitgen main.go
./commitgen install

Requirements

• Go 1.19+
• Git
• AI CLI commands with proper API configuration (any of these):
  • claude for Claude (Anthropic)
  • gemini for Gemini (Google)
  • copilot for Copilot (GitHub)
  • opencode for OpenCode
  • kilo for Kilo
  • cursor-agent for Cursor
  • aider for Aider
  • Or any custom AI CLI tool (add with commitgen provider add)
• Unix-like system (Linux, macOS)

Advanced Usage

Custom Git Diff Analysis

Commitgen automatically analyzes git changes and provides context to the AI model:

• Staged changes: Uses git diff --cached to review staged modifications
• All changes: Combines modified files and untracked files for comprehensive analysis
• Untracked files: Reads content of new files that haven't been added to git yet

Troubleshooting

Common Issues

"not in a git repository"

• Make sure you're in a directory with a .git folder
• Run git init if starting a new repository

"no changes found to analyze"

• Stage some files with git add <files>
• Or use commitgen commit all to include unstaged changes
• Use commitgen commit untracked for new files

"failed to call [provider] API"

• Ensure the AI CLI command is available in your PATH
• Verify API keys are properly configured
• Test the AI CLI command directly: claude or gemini or copilot or opencode

Provider-Specific Setup

OpenCode

# Install OpenCode
curl -fsSL https://opencode.ai/install.sh | bash
# Login
opencode auth login

Claude (Default)

# Install claude
pip install claude
# Configure API key in environment
export ANTHROPIC_API_KEY="your-key-here"

Gemini

# Install Gemini CLI
npm install -g @google-cloud/vertexai
# Configure authentication
gcloud auth application-default login

Copilot

# Install GitHub CLI with Copilot extension
gh extension install github/gh-copilot
# Login to GitHub
gh auth login

Integration with Git Hooks

You can integrate commitgen into your git workflow using hooks:

# Set up prepare-commit-msg hook
echo '#!/bin/bash
if [ -z "$2" ]; then
  ./commitgen --provider claude > .git/COMMIT_EDITMSG.tmp
  if [ -f .git/COMMIT_EDITMSG.tmp ]; then
    cat .git/COMMIT_EDITMSG.tmp > "$1"
    rm .git/COMMIT_EDITMSG.tmp
  fi
fi' > .git/hooks/prepare-commit-msg

chmod +x .git/hooks/prepare-commit-msg

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

License

MIT License - see LICENSE file for details.