aiautocommit

Generate Commit Messages With AI

aiautocommit analyzes your staged changes and creates conventional commit messages.

Yes, there are a lot of these. Main ways this is different:

• Ability to easily customize prompts on a per-repo basis (.aiautocommit file or folder)
• Exclusions (e.g., lock files) that generate messages without hitting LLMs
• Support for multiple AI providers via pydantic-ai, with Google Gemini as the default
• Tastefully written prompts by a real engineer who cares

Installation

uvx aiautocommit

Note: OpenAI, Anthropic, and Gemini (Google) are supported by default. To install all providers supported by Pydantic AI, use pip install "aiautocommit[all-providers]".

Features

• Generates conventional commit messages
• Customizable prompts and exclusions
• Pre-commit hook integration
• Supports custom config directories
• CLI flag for version checking (--version)
• Automatically includes the current git branch name in the AI prompt for improved context
• Does not generate a commit during a merge or reversion (when an existing autogen'd msg exists)
• Automatic lock file handling: lock files (e.g., uv.lock, package-lock.json) generate conventional messages (e.g., chore(deps): update uv.lock) even when they are excluded from the AI prompt.

Getting Started

Set your API key (works for any provider, Google Gemini is the default):

export AIAUTOCOMMIT_AI_KEY=<YOUR API KEY>
export AIAUTOCOMMIT_MODEL=google:gemini-3.8-flash

Stage your changes and run aiautocommit:

git add .

# this will generate a commit message and commit the changes
aiautocommit commit

# or, just to see what it will do
aiautocommit commit --print-message

Using the CLI directly is the best way to debug and tinker with the project as well.

Automatic Lock File Handling

Lock files (like uv.lock, package-lock.json, Gemfile.lock, etc.) are frequently updated but don't provide much context for an AI-generated message. By default, these are excluded from the AI prompt to save tokens and improve quality.

However, if you stage only lock files, aiautocommit will detect them and automatically generate a conventional commit message:

• uv.lock -> chore(deps): update uv.lock
• package-lock.json -> chore(deps): update package-lock.json
• Mixed lock files -> chore(deps): update lock files
• ... and more

If any non-lock files are staged alongside them, the AI will ignore the lock files (based on your exclusions) and focus on the code changes.

Pull Request Context

To provide even better commit messages, aiautocommit can automatically pull in the title and body of the pull request associated with your current branch. This gives the AI full context of the "why" behind your changes.

This feature is disabled by default to keep execution fast. To enable it:

export AIAUTOCOMMIT_INCLUDE_PR_CONTEXT=true

How it works:

1. Detection: It checks your local git config or tracking branch for a PR number. If not found, it uses the GitHub CLI (gh) to find an open PR for the current branch.
2. Caching: Once fetched, the PR content is cached in .git/aiautocommit/<PR_NUMBER>_pull_request.md for 2 hours.
3. Speed: If no PR is found, a "not found" marker is cached for 1 hour to prevent repeated network calls on local-only branches.
4. Manual Edits: You can manually edit the cached Markdown file in .git/aiautocommit/ if you want to refine the context sent to the AI.

Requirements:

• GitHub CLI (gh) installed and authenticated.

Customization

Logging

First, you'll want to enable logging so you can extract the diff and prompt and iterate on it in ChatGPT:

export AIAUTOCOMMIT_LOG_LEVEL=DEBUG
export AIAUTOCOMMIT_LOG_PATH=aiautocommit.log

Now, you'll have a log you can tail and fiddle with from there.

Additional debugging commands:

# Print the compiled system prompt (after all config files are merged)
aiautocommit output-prompt

# Print the compiled file exclusions list
aiautocommit output-exclusions

# Generate a ChatGPT-ready debug block for a past commit to help iterate on the prompt
aiautocommit debug-prompt <sha> "the commit message was too vague"

# Ignore commands.md and instructions.md in home-level AI harness ignore files
aiautocommit global-ignores --dry-run
aiautocommit global-ignores

debug-prompt outputs the diff, the generated commit message, and the full prompt in a format you can paste directly into ChatGPT to get suggestions for improving the prompt.

Using Config Directory

aiautocommit looks for configuration files in these locations (in priority order):

• .aiautocommit in git root (or current directory) — as a directory for full config, or a file to append to the default prompt
• $XDG_CONFIG_HOME/aiautocommit/ (defaults to ~/.config/aiautocommit/)
• Custom path via aiautocommit_CONFIG environment variable

To get started with customization:

aiautocommit dump-prompts

This creates a .aiautocommit/ directory with:

• commit_prompt.txt: Template for generating commit messages
• excluded_files.txt: List of files or glob patterns (e.g., mise*lock) to exclude from processing
• commit_suffix.txt: Git trailers appended to every generated message (default Generated-by: aiautocommit). Trailers are stacked into one block after a blank line at the end of the subject/body — including trailers the model already wrote, such as Dev-Note:.

If you create .aiautocommit/examples/example_1.md, example_2.md, and so on, they are appended to the prompt in filename order as few-shot examples. Keep them small and use this format:

<example>
<diff>
diff --git ...
</diff>

<diffAnalysis>
- short|medium|large diff
- omit body | include body
- primary change: one-line intent
</diffAnalysis>

<commitMessage>
feat: concise subject

- optional body bullet
</commitMessage>
</example>

Lightweight Prompt Extension

If you only want to extend the default prompt rather than replace it entirely, create a plain .aiautocommit file (not a directory) in your repo root. Its contents will be appended to the stock commit_prompt.txt:

echo "Always include the ticket number from the branch name in the subject line." > .aiautocommit

This is the simplest way to add project-specific instructions without duplicating the full default prompt.

Installing Pre-commit Hook

To automatically generate commit messages during git commits:

aiautocommit install

Learn more about git hooks here.

Customize Scopes

First, dump the prompts into your project:

aiautocommit dump-prompts

Then add your scope specification to the commit prompt:

<scopes>
Optional scopes (e.g., `feat(api):`):
- `api`: API endpoints, controllers, services.
- `frontend`: React components, styles, state management.
- `migration`: Database schema changes.
- `jobs`: Background jobs, scheduled tasks.
- `infra`: Infrastructure, networking, deployment, containerization.
- `prompt`: Updates to LLM or AI prompts.
</scopes>

Lefthook Configuration

Lefthook is a tool for managing git hooks. To use aiautocommit with lefthook, add the following to your .lefthook.yml:

prepare-commit-msg:
  commands:
    aiautocommit:
      run: aiautocommit commit --output-file "{1}"
      interactive: true
      env:
        # without this, lefthook will run in an infinite loop
        LEFTHOOK: 0
        # ensures that LOG_LEVEL config of the current project does not interfere with aiautocommit
        AIAUTOCOMMIT_LOG_LEVEL: info
      skip:
        merge:
        rebase:
        # only run this if the tool exists
        run: ! which aiautocommit > /dev/null

Environment Variables

All environment variables used by aiautocommit or its providers can be prefixed with AIAUTOCOMMIT_ to take precedence over the standard variable.

• AIAUTOCOMMIT_AI_KEY: Universal API key. aiautocommit internally maps this to the correct provider-specific variable (e.g., GOOGLE_API_KEY, OPENAI_API_KEY) based on your active model.
• AIAUTOCOMMIT_MODEL: AI model to use, in provider:model format (default: google:gemini-3.8-flash). Examples: anthropic:claude-3-5-sonnet-latest, openai:gpt-4o.
• AIAUTOCOMMIT_CONFIG: Custom config directory path
• AIAUTOCOMMIT_LOG_LEVEL: Logging verbosity
• AIAUTOCOMMIT_LOG_PATH: Custom log file path

Ensure you have the corresponding API key set in AIAUTOCOMMIT_AI_KEY.

Model Configuration

aiautocommit uses pydantic-ai under the hood, supporting a wide range of providers including OpenAI, Anthropic, and Gemini (via VertexAI or Generative AI) by default. You can specify the model using the provider:model syntax in the AIAUTOCOMMIT_MODEL environment variable.

Google Gemini models use pydantic-ai's unified thinking setting at low effort. minimal is not used: newer Gemini models reject it.

Common examples:

• google:gemini-3.8-flash (default)
• openai:gpt-4o
• anthropic:claude-3-5-sonnet-latest
• ollama:llama3 (for local models)

Ensure you have the corresponding API key set in your environment (e.g., ANTHROPIC_API_KEY for Anthropic models).

Example: Meta Muse

Meta's Model API at dev.meta.ai is OpenAI-compatible. Because Pydantic AI does not yet have a dedicated meta: provider class, use the openai: prefix along with AIAUTOCOMMIT_OPENAI_BASE_URL:

export AIAUTOCOMMIT_MODEL="openai:muse-spark-1.3-contributor"
export AIAUTOCOMMIT_OPENAI_BASE_URL="https://api.meta.ai/v1"

Difftastic

Difftastic integration was removed. While difftastic produces semantically richer diffs, LLMs do not interpret its output format well, leading to worse commit messages than standard git diff.

Writing Commit Messages

Some guides to writing commit messages:

• https://cbea.ms/git-commit/
• https://groups.google.com/g/golang-dev/c/6M4dmZWpFaI
• https://github.com/RomuloOliveira/commit-messages-guide
• https://gist.github.com/qoomon/5dfcdf8eec66a051ecd85625518cfd13

Credits

This project inspired this project. It had a simple codebase. I've taken the idea and expanded it to include more features, specifically per-project prompt customization.

Related Projects

I looked at a bunch of projects before building this one.

• https://github.com/abi/aiautocommit - python, inactive. Many files, not simple.
• https://github.com/Sett17/turboCommit - rust, inactive.
• https://github.com/Nutlope/aicommits - typescript. Node is so slow and I hate working with it.
• https://github.com/Elhameed/aicommits - python
• https://github.com/zurawiki/gptcommit - active, rust. Too complicated and no prompt customization.
• https://github.com/ywkim/gpt-commit - lisp, inactive.
• https://github.com/markuswt/gpt-commit - single file, python based. No commits > 1yr. Very simple codebase.
• https://github.com/josenerydev/gpt-commit - also python
• https://github.com/di-sukharev/opencommit - has conventional commit structure

---

This project was created from iloveitaly/python-package-template