aicmt

AI-powered Git commit message generator supporting OpenAI, Ollama, Gemini, and OpenRouter.

🚀 Quick Start

git add .
npx aicmt

• Generates a commit message for your staged changes using AI.
• Commits automatically (unless you use --dry or --edit).

Prerequisites

• Node.js v16 or newer
• git (any recent version)
• npx (comes with Node.js)
• An account/API key for your chosen AI provider (OpenAI, Gemini, OpenRouter, or a running Ollama instance)

Where to Use

• Run in any git repository (local or remote)
• Works on Windows, macOS, and Linux

Installation & Usage

You do not need to install globally. Just use npx:

git add .
npx aicmt [--dry] [--emoji] [--style <style>] [--provider <ollama|openai|gemini|openrouter>] [--model <model_name>] [--validate] [--edit] [--no-auto-stage] [--type <type>] [--scope <scope>] [--prompt <prompt>]

Features

• Generates commit messages from staged git diff using AI
• Supports OpenAI, Ollama (local), Google Gemini, and OpenRouter
• Free models by default: OpenRouter defaults to free models unless you specify a paid one with --model
• Emoji and style options
• Configurable via CLI flags, .aicmtrc.json, or environment
• Commit message validation: Ensures messages follow Conventional Commits standard with helpful suggestions
• Auto-staging: Automatically stages all changes before generating commit messages
• Progress indicators: Visual feedback during message generation, staging, and validation

Provider Selection & Configuration

• The provider is chosen in the following order of precedence:
  1. CLI flag (--provider)
  2. .aicmtrc.json config file (in your project root)
  3. Environment variables (API keys)
• Ollama is only used if you explicitly select it as your provider.
• Config file location: .aicmtrc.json in your project root
• Environment variables: Set in .env (not committed)
  • OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY

Example Commands

Generate a commit message with the default provider/model:

npx aicmt

Use a specific free OpenRouter model:

npx aicmt --provider openrouter --model google/gemini-2.0-flash-exp:free

Force the commit type and scope:

npx aicmt --type fix --scope core

Edit the message before committing:

npx aicmt --edit

Preview the message (dry run):

npx aicmt --dry

Validate the message:

npx aicmt --validate

Use a custom prompt for the AI:

npx aicmt --prompt "Write a detailed, specific Conventional Commit message for this change."

Set up or change your default provider/model:

npx aicmt --setup

How to Avoid Generic Commit Messages

• The tool uses a strict prompt and retries to avoid generic messages like fix: update.
• If the AI still produces a generic message, try:
  • Using a more powerful model (e.g., OpenAI GPT-4)
  • Providing a custom prompt with --prompt
  • Editing the message with --edit
• You can force the type and scope with --type and --scope for more control.
• If the message is still too generic, the tool will warn you and suggest editing.

How to Use

1. Setup (First Time Only)

Run the setup command to select your default AI provider and model:

npx aicmt --setup

This will create a .aicmtrc.json file with your preferences.

2. Stage Your Changes

Add your changes to the git staging area:

git add .

Note: aicmt now auto-stages changes by default. Use --no-auto-stage to disable this behavior.

3. Generate a Commit Message

Run the tool to generate and commit with an AI-generated message:

npx aicmt

4. Preview the Commit Message (Dry Run)

To preview the generated message without committing:

npx aicmt --dry

5. Edit the Generated Message Before Committing

To review and edit the message in your editor before committing:

npx aicmt --edit

6. Customize Provider, Model, Style, Emoji, Type, Scope, and Language

Override defaults using CLI flags:

npx aicmt --provider openai --model gpt-4 --style snarky --emoji --lang en --type docs --scope api

7. Validate Commit Messages

Ensure your commit messages follow the Conventional Commits standard:

npx aicmt --validate
npx aicmt --edit --validate

8. Use a Custom Prompt

Provide your own prompt template:

npx aicmt --prompt "Write a haiku about this diff."

9. Help

See all available options:

npx aicmt --help

Validation

aicmt includes built-in validation to ensure your commit messages follow the Conventional Commits standard:

• Format: type(scope): description
• Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
• Length: Maximum 72 characters
• Suggestions: Automatic suggestions for fixing invalid messages

Validation Examples

# Validate a generated message
npx aicmt --validate

# Edit with validation feedback
npx aicmt --edit --validate

# Dry run with validation
npx aicmt --dry --validate

The validation will show:

• ✅ Green checkmark for valid messages
• ⚠️ Yellow warnings for issues
• 💡 Blue suggestions for improvements
• 🔧 Cyan suggested fixes

Troubleshooting & FAQ

Q: I get an error about missing API keys!

• Make sure you have set the correct API key in your .env file or as an environment variable.
• Example .env:

  OPENAI_API_KEY=sk-...
  GEMINI_API_KEY=...your_key...
  OPENROUTER_API_KEY=...your_key...

Q: Ollama is not found!

• Ensure Ollama is running locally and accessible.
• Use --provider ollama to force using it.

Q: The tool doesn't stage my changes!

• By default, aicmt auto-stages. Use --no-auto-stage to disable.

Q: How do I reset my config?

• Delete .aicmtrc.json and rerun npx aicmt --setup.

Q: How do I use this in CI?

• Set environment variables for your API keys and use the CLI as part of your workflow.

Q: Why does the tool sometimes use 'feat' as the type?

• The AI model will default to 'feat' (feature) if it is unsure about the type of change. To override this, use the --type <type> flag or edit the message manually with --edit. There is currently no way to force the AI to always pick the correct type automatically.

Q: How do I avoid generic commit messages like 'fix: update'?

• Use a more powerful model, a custom prompt, or the --edit flag. The tool will warn you if the message is too generic and suggest editing.

Q: How do I use only free models?

• By default, OpenRouter will only show free models in setup. To use a paid model, specify it with --model.

Local Development / Manual Installation

Clone the repo and run locally:

git clone <this-repo-url>
cd aicmt-test
npm install
node bin/index.js [args]

Security

• Do not commit your .env file.

Release & Pre-release Workflow

• To create an official release, set the version in your package.json (e.g., 1.0.0) and run:

  npx aicmt release --type major|minor|patch

• To create a pre-release (e.g., beta, rc), set the version to a pre-release string (e.g., 1.0.0-beta.1) in package.json and run:

  npx aicmt release --type prerelease

• The tool will use the exact version from package.json for the git tag and changelog entry, supporting both standard and pre-release versions.
• The changelog is automatically generated from all commit messages since the last tag, grouped by type (feat, fix, docs, etc.).
• Tags like v1.0.0-beta.1 are fully supported for beta/rc releases.

License

This project is licensed under the terms of the MIT license. See the LICENSE file for details.