Commit Suggester

A simple CLI tool that uses AI to generate conventional commit messages for your git changes.

Features

• 🤖 Multiple AI Providers - Groq, OpenAI, Anthropic, Google Gemini
• 🚀 Auto-staging - Automatically stages all changes before analysis
• 🔍 Dry Run Mode - Preview suggestions without committing
• 📦 Staged Only Mode - Analyze only pre-staged changes
• ⚡ Simple Setup - Just set environment variables
• 🎯 Smart Analysis - Analyzes your actual git diffs
• 📝 Conventional Commits - Follows standard format
• ✨ Interactive - Choose from 3 AI suggestions or write custom

Quick Setup

Installation

# Install globally with npm
npm install -g commit-suggester

# Or with Bun
bun install -g commit-suggester

Setup API Key (choose one):

# Recommended - Groq (fast & free)
export GROQ_API_KEY="your_groq_key_here"

# Or use others
export OPENAI_API_KEY="your_openai_key_here"
export ANTHROPIC_API_KEY="your_anthropic_key_here"
export GOOGLE_GENERATIVE_AI_API_KEY="your_google_key_here"

# Add to your shell profile
echo 'export GROQ_API_KEY="your_key"' >> ~/.zshrc
source ~/.zshrc

Ready to Use!

commit-suggester           # Auto mode
commit-suggester -i        # Interactive mode
commit-suggester -d        # Dry run (preview only)
commit-suggester -s        # Staged only (skip auto-staging)

Get API Keys

• Groq (Recommended): console.groq.com/keys - Fast & Free
• OpenAI: platform.openai.com/api-keys
• Anthropic: console.anthropic.com
• Google: ai.google.dev/tutorials/setup

Usage

Auto Mode (Default)

# Make your changes
echo "console.log('hello')" > test.js

# Auto-commit with best suggestion
commit-suggester

Output:

🚀 Commit Suggester - AI-powered Git Commits

📦 Staging all changes...
📊 Analyzing changes...
✅ Found 1 file(s): +1/-0

🤖 Using GROQ AI (llama-3.3-70b-versatile)
🤖 Generating commit suggestions...

🎯 Auto-selected: "feat: add hello world console log"

📝 Committing changes...
✅ Committed successfully!

🎉 Successfully committed: "feat: add hello world console log"

Interactive Mode

# Choose from 3 options + custom
commit-suggester -i

Output:

🚀 Commit Suggester - AI-powered Git Commits

📦 Staging all changes...
📊 Analyzing changes...
✅ Found 1 file(s): +1/-0

🤖 Using GROQ AI (llama-3.3-70b-versatile)
🤖 Generating commit suggestions...

📋 Interactive Mode - Choose your commit message:

? Select a commit message:
❯ [1] feat: add hello world console log
  [2] chore: create test javascript file
  [3] feat(test): add basic console output
  ✏️  Write custom message

? Commit with: "feat: add hello world console log"? Yes

📝 Committing changes...
✅ Committed successfully!

🎉 Successfully committed: "feat: add hello world console log"

Dry Run Mode

Preview AI suggestions without actually committing:

commit-suggester -d
# or
commit-suggester --dry-run

Output:

🚀 Commit Suggester - AI-powered Git Commits

🔍 Dry run mode - no commit will be made

📦 Staging all changes...
📊 Analyzing changes...
✅ Found 1 file(s): +1/-0

🤖 Using GROQ AI (llama-3.3-70b-versatile)
🎯 Auto-selected: "feat: add hello world console log"

🔍 Dry run - would commit: "feat: add hello world console log"
Run without --dry-run to actually commit.

Staged Only Mode

Only analyze files you've already staged (respects your manual staging):

# Stage specific files manually
git add src/feature.ts

# Analyze only staged files
commit-suggester -s
# or
commit-suggester --staged

Combining Options

Options can be combined for more control:

commit-suggester -i -d     # Interactive + dry run
commit-suggester -i -s     # Interactive + staged only
commit-suggester -s -d     # Staged only + dry run

Help

commit-suggester --help

Output:

🚀 Commit Suggester - AI-powered Git Commits

Usage:
  commit-suggester              # Auto-select best commit message
  commit-suggester -i           # Interactive mode (3 options + custom)
  commit-suggester -d, --dry-run # Preview suggestions without committing
  commit-suggester -s, --staged  # Only use already staged changes
  commit-suggester --help        # Show this help

Options can be combined:
  commit-suggester -i -d         # Interactive + dry run
  commit-suggester -i -s         # Interactive + staged only

Setup:
  export GROQ_API_KEY="your_key"      # Recommended - Fast & Free
  export OPENAI_API_KEY="your_key"    # Alternative
  export ANTHROPIC_API_KEY="your_key" # Alternative

How it Works

Auto Mode:

1. Auto-stages all your changes (git add .)
2. Analyzes git diffs to understand what changed
3. Generates 3 AI suggestions (best one first)
4. Auto-commits with the best suggestion

Interactive Mode (-i):

1. Auto-stages all your changes (git add .)
2. Analyzes git diffs to understand what changed
3. Shows 3 AI suggestions + custom option
4. Interactive selection with confirmation
5. Commits with your chosen message

Dry Run Mode (-d):

1. Stages changes (unless -s flag used)
2. Analyzes git diffs
3. Generates AI suggestions
4. Displays what would be committed (no actual commit)

Staged Only Mode (-s):

1. Skips auto-staging (uses your manually staged files)
2. Analyzes only staged changes
3. Generates AI suggestions
4. Commits (unless -d flag used)

CLI Options Reference

| Flag | Short | Description | |------|-------|-------------| | --interactive | -i | Choose from 3 suggestions + custom input | | --dry-run | -d | Preview suggestions without committing | | --staged | -s | Only analyze already-staged changes | | --help | -h | Show help information |

Supported Commit Types

• feat: New features
• fix: Bug fixes
• docs: Documentation
• style: Code style changes
• refactor: Code refactoring
• test: Tests
• chore: Maintenance
• perf: Performance improvements

Project Structure

src/
├── cli.ts              # Main CLI interface
├── CommitSuggester.ts  # Core logic
├── services/
│   ├── AIService.ts    # AI provider handling
│   └── GitService.ts   # Git operations
└── types/
    └── index.ts        # TypeScript types

Development

# Clone and setup
git clone https://github.com/rishinpoolat/commit-suggester.git
cd commit-suggester
bun install

# Run in development
bun run dev

# Build
bun run build

# Type check
bun run typecheck

# Test locally
bun link
commit-suggester

License

MIT - See LICENSE file for details.