git-commit-msg-ai 1.8.0

AI-powered git commit message generator following Conventional Commits

git-commit-msg-ai

AI-powered git commit message generator that follows the Conventional Commits specification.

Prerequisites

• Python 3.10+

• An Anthropic API key set as an environment variable:

  export ANTHROPIC_API_KEY=sk-ant-...   # macOS/Linux
  

  [System.Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', 'sk-ant-...', 'User')   # Windows
  

Development Setup

Clone the repository, create a virtual environment, and install the project in editable mode with all dev dependencies:

python -m venv .venv

Activate the virtual environment:

# macOS/Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

Install the project and dev dependencies:

pip install -e ".[dev]"

After activation the git-commit-msg-ai entry-point is on your PATH. You can also run the dev toolchain:

pytest          # run tests with coverage
ruff check .    # lint
mypy .          # type-check

Installation

pip install git-commit-msg-ai

Usage

Stage your changes, then run the tool from inside any git repository:

git add <files>
git-commit-msg-ai

The tool will:

1. Read your staged diff
2. Generate a commit message using Claude AI
3. Print the message and prompt you to choose:

[a]ccept / [e]dit / [r]eject:

• a - commits immediately with the generated message
• e - opens the message in your $EDITOR (defaults to notepad on Windows, vi on Linux/macOS), lets you modify it, then commits
• r - exits without committing

Commit message format

Generated messages follow the Conventional Commits specification:

<type>(<optional scope>): <short subject>

- Bullet explaining why this change was made
- Another reason if applicable

For breaking changes, the subject line gets a ! and a footer is added:

feat(api)!: remove deprecated endpoint

- Endpoint was unused and blocking the new auth rollout

BREAKING CHANGE: /v1/legacy is no longer available

Supported types: feat, fix, docs, style, refactor, test, chore

CI/CD

Every push to main and every pull request runs the full CI pipeline (lint, type-check, tests, build).

Pushing a version tag (e.g. v1.5.2) triggers the CD pipeline:

1. Tests are re-run as a gate
2. The tag version is verified to match the version in pyproject.toml
3. The package is built and published to PyPI
4. A GitHub Release is created with release notes generated by Claude Haiku from the commit log

Releasing a new version:

# 1. Bump the version in pyproject.toml
# 2. Commit and push
git add pyproject.toml
git commit -m "chore: bump version to 1.5.2"
git push origin main
# 3. Tag and push - this triggers the CD pipeline
git tag v1.5.2
git push origin v1.5.2

Debugging

By default the tool produces no diagnostic output. To enable logging, set the GIT_COMMIT_AI_LOG_LEVEL environment variable before running the command. Logs are written to stderr and do not interfere with the generated commit message on stdout.

Valid values: DEBUG, INFO, WARNING, ERROR, CRITICAL

# macOS/Linux - show all internal diagnostic messages
GIT_COMMIT_AI_LOG_LEVEL=DEBUG git-commit-msg-ai

# Windows PowerShell
$env:GIT_COMMIT_AI_LOG_LEVEL = 'DEBUG'
git-commit-msg-ai

Level	What you see
DEBUG	git commands run, API model/token params, temp file paths, char counts
INFO	commit message generated (with char count), commit created
WARNING	no staged changes found
ERROR	git not found, API failures, editor errors