ai-commit

ai-commit is a small CLI tool that writes better git commit messages for you.

It reads your staged git diff, sends a cleaned summary of those changes to an LLM, and suggests 3 concise commit messages in Conventional Commit format.

Instead of writing commits like:

• fix stuff
• update
• changes

You get suggestions like:

• feat: add OAuth login flow
• fix: handle missing session token
• docs: update API auth examples

Why use it?

• Saves time when you do not want to think about commit wording
• Produces cleaner, more consistent commit history
• Encourages Conventional Commit style automatically
• Lets you review and choose before anything is committed

How it works

ai-commit follows this flow:

1. Reads your staged git changes
2. Cleans and truncates the diff
3. Sends that context to OpenAI
4. Generates 3 commit message suggestions
5. Lets you choose one, regenerate, or quit
6. Runs git commit -m "..." for you

Installation

Clone or open this project, then install it locally:

pip install -e .

After that, the ai-commit command will be available in your shell.

Requirements

• Python 3.10+
• Git installed and available on your PATH
• An OpenAI API key

Setup your API key

ai-commit needs an OpenAI API key to generate commit messages.

You have 2 simple options:

Option 1: Set it once in your shell

macOS / Linux:

export OPENAI_API_KEY="your_api_key"

Windows PowerShell:

$env:OPENAI_API_KEY="your_api_key"

You can also use:

AI_COMMIT_OPENAI_API_KEY

That is useful if you want a key that is only used for this tool.

Option 2: Let ai-commit ask you

If you do not set a key in advance, ai-commit will prompt you for it when you run the command.

Your input is hidden while typing for safety.

Basic usage

Stage your changes first:

git add .

Then run:

ai-commit

Example flow:

⚡ Analyzing staged changes...
✔ Found staged changes in 3 file(s)
⚡ Generating commit messages...

Suggested commit messages:
1. feat: add OAuth login handler
2. fix: handle missing auth token
3. refactor: simplify session validation

Select option (1-3), r to regenerate, or q to quit:

CLI options

ai-commit

Generate commit suggestions and create a normal commit.

ai-commit --dry

Generate suggestions, but do not run git commit.

Useful when you just want message ideas.

ai-commit --amend

Generate a new message and amend the latest commit:

git commit --amend -m "your message"

ai-commit --emoji

Adds emoji-style commit prefixes when appropriate.

Examples:

• ✨ feat: add login page
• 🐛 fix: handle missing token
• ♻️ refactor: simplify auth flow
• 📝 docs: update setup guide

Commit style rules

The generated messages are designed to be:

• Conventional Commits
• imperative in tone
• one line only
• under 72 characters
• without trailing punctuation

Examples:

• feat: add GitHub login support
• fix: prevent crash on empty config
• refactor: simplify commit prompt builder
• docs: add installation instructions

Safety features

ai-commit includes a few safety protections:

• It only works on staged changes
• It strips noisy diff metadata before sending anything
• It truncates large diffs to control prompt size and cost
• It warns when it detects potentially sensitive content
• It blocks suspicious diffs in non-interactive environments
• It redacts secrets from API error messages where possible

Sensitive diff protection

If your staged diff appears to include secrets or sensitive files such as:

• .env
• private keys
• API keys
• tokens
• credentials

ai-commit will warn you before uploading that diff to OpenAI.

In non-interactive environments, it refuses to continue by default.

If you really want to override that behavior, you can set:

AI_COMMIT_ALLOW_SENSITIVE=1

Use that carefully.

Model configuration

By default, ai-commit uses:

gpt-4.1-mini

You can override the model with:

AI_COMMIT_MODEL

Example:

export AI_COMMIT_MODEL="gpt-4.1"

Example workflows

Normal commit

git add .
ai-commit

Dry run only

git add .
ai-commit --dry

Amend previous commit

git add .
ai-commit --amend

Use emoji commits

git add .
ai-commit --emoji

Error cases you may see

No staged changes

You need to stage files first:

git add <files>

Git not installed

Install Git and make sure it is available from your terminal.

Missing OpenAI dependency

Install project dependencies again:

pip install -e .

Missing API key

Set OPENAI_API_KEY or AI_COMMIT_OPENAI_API_KEY, or just run the command and enter the key when prompted.

Project structure

ai_commit.py
pyproject.toml
tests/

Testing

This project includes unit and integration tests.

Run them with:

python -m unittest discover -s tests -v

Built for local developer use

ai-commit is intentionally minimal:

• one small Python entrypoint
• easy local install
• no heavy setup
• practical defaults

It is designed for developers who want a fast, clean command they can use every day.