Commit AI

Commit AI is a powerful and intelligent CLI tool that leverages the Google Gemini API to automatically generate conventional commit messages from your staged git changes. It streamlines your workflow by analyzing your code modifications and suggesting clear, well-formatted commit messages, allowing you to focus on what matters most: coding.

The tool is highly configurable, efficient with large changesets, and designed to integrate seamlessly into any developer's toolkit.

Features

• 🤖 Intelligent Commit Generation: Uses the Gemini AI to understand your code changes and create meaningful commit messages.
• ⚙️ Highly Configurable: Customize commit conventions, message format, and more via a simple JSON file (~/.commit-ai/config.json).
• 🔐 Secure API Key Storage: Your API key is stored locally and securely in your home directory (~/.commit-ai/api-key).
• ** efficient Large Diff Handling:** Automatically summarizes large diffs in chunks to handle substantial changes without hitting API limits.
• ✨ Clean Terminal UI: A custom single-line ASCII loader provides status updates without cluttering your terminal.
• 🚀 Workflow Automation: Flags for auto-committing (-a) and piping output (-s) to other commands.

How It Works

1. Detects Changes: Scans your repository for any staged changes (git diff --staged).
2. Cleans Diff: Summarizes noisy files like package-lock.json to create a clean, token-efficient diff.
3. Summarizes (If Needed): If the diff is very large, it's broken into chunks, summarized individually by the AI, and then combined into a final summary.
4. Builds Prompt: Constructs a detailed prompt for the AI based on the cleaned diff/summary and your custom rules from config.json.
5. Generates Message: Calls the Gemini API to generate the final commit message.
6. Displays & Commits: Prints the message to the console and, if requested, automatically commits it for you.

Setup

Prerequisites

• Node.js (v18 or higher recommended)
• Git

1. Installation

Clone the repository and install the tool globally using npm or pnpm:

# Clone the project (if you haven't already)
git clone https://github.com/mktawileh/commit-ai
cd commit-ai

# Install globally
npm install -g .

2. Configuration

The first time you run commit-ai, it will automatically create a configuration directory at ~/.commit-ai.

A. Add Your API Key: You need a Google Gemini API key. You can get one for free from Google AI Studio.

Once you have your key, open the newly created file at ~/.commit-ai/api-key and paste your key into it.

B. Customize Commits (Optional): You can tailor the AI's behavior by editing ~/.commit-ai/config.json. The default configuration is:

{
  "convention": "conventional",
  "multiline": true,
  "lowercase": false,
  "customRules": [
    "The subject line should be concise, clear, and under 50 characters.",
    "If the changes are significant, add a detailed, bulleted body explaining the 'what' and 'why'."
  ]
}

Usage

1. Navigate to your git repository.
2. Stage your changes (git add .).
3. Run the tool:

   commit-ai [flags]
   

Flags

Flag	Alias	Description
--auto-commit	-a	Automatically commit the generated message.
--silent	-s	Output only the final commit message (for piping).
--cache		Enable caching (default). Use --no-cache to disable.

Examples

Standard Generation:

commit-ai

This will generate a message and print it for you to copy.

Generate and Auto-Commit:

commit-ai -a

This will generate the message and immediately create the commit.

Disable Cache for a one-off run:

commit-ai --no-cache

Forces regeneration even if an identical diff/config was seen before.

Pipe to Clipboard (macOS):

commit-ai -s | pbcopy

This puts the generated message directly into your clipboard.

License

MIT License