cai

cai is a Git extension that automates the creation of commit messages.
Simply run git cai to generate a meaningful, context-aware commit message based on the changes in your repository.

cai uses a Large Language Model (LLM) to analyse diffs and new files, producing concise and informative commit messages.

Currently supported providers:

• OpenAI
• Gemini
• Anthropic
• Groq
• xAI
• Mistral
• DeepSeek
• Ollama (local)

---

Prerequisites

• Python 3.10 or higher
• pipx
• Either:
  • Ollama installed and running locally, or
  • An API key for at least one of the following providers:
  • OpenAI
  • Gemini (free tier available)
  • Anthropic
  • Groq (free tier available)
  • xAI
  • Mistral
  • DeepSeek

---

Features

• Automatically detects added, modified, and deleted files
• Generates meaningful, context-aware commit messages using an LLM
• Seamless integration with Git
• Supports multiple LLM providers and models
• Override provider and model per invocation (-P, -m)
• Global configuration with per-repository overrides
• Repository-specific language, style, and model selection
• Amend the last commit message with a regenerated one (-A)
• Conventional Commits format support (-C)
• Change configuration from the command line (-S, -H)
• Optional commit squashing with automatic summary generation (all, last N, or up to a specific commit)
• List providers, models, active config, and file paths (-l)
• Token usage logging for API calls
• Branch name as LLM context via --branch / -b
• Extra context for the LLM via --context / -x (e.g. ticket numbers, reasons)
• Generation time measurement (-t)
• Shell completion for bash, zsh, and fish (-i)

---

Installation

Install cai using pipx:

pipx install git-cai-cli

Ensure that pipx binaries are available in your PATH:

pipx ensurepath

Restart your shell after installation.

If you are running Arch Linux or an Arch-based distribution such as EndeavourOS, CachyOS, etc., you can install the package from the AUR using a package manager like Paru.

paru -S cai

---

Usage

Once installed, cai works like a standard Git command:

git cai

cai uses the output of git diff to generate a commit message.
The generated message is opened in your configured Git editor, allowing you to review or edit it before committing.

In short: it behaves like git commit, but the commit message is pre-filled.

Ignoring files

To exclude specific files or directories from being considered when generating commit messages, create a .caiignore file in the root of your repository.

• Files listed in .gitignore are always excluded
• .caiignore is intended for tracked files that should not influence commit messages

The syntax is identical to .gitignore.

---

Configuration

On first execution, cai automatically creates the base configuration in your home directory.

• Global configuration:
  ~/.config/cai/cai_config.yml

• API tokens:
  ~/.config/cai/tokens.yml

It also creates two Markdown prompt files:

• Default commit prompt:
  ~/.config/cai/commit_prompt.md
• Default squash prompt:
  ~/.config/cai/squash_prompt.md

Don't be scared the first run will show an error. It only misses a token. Add your provider API keys to tokens.yml. Once configured, cai will reuse them automatically. Set your preferred LLM in cai_config.yml (Groq by default).

If you want to use Ollama, set default: ollama and configure the ollama: block (model/temperature). Ollama is automatically started when used.

Custom prompts (Markdown)

The generated commit message is guided by prompt files.

• By default, cai_config.yml points to the auto-created prompt files in ~/.config/cai/.
• To use your own prompts in a repository, generate templates at the root of the repository:

git cai -p

This creates:

• commit_prompt.md
• squash_prompt.md

Then set prompt_file and/or squash_prompt_file in your cai_config.yml (also repo) to point to those files.

Repository-specific configuration

Each repository can be configured independently.

If a cai_config.yml file exists in the root of a repository, cai will use it instead of the global configuration.
This allows different projects to use different providers, models, languages, and styles.

Examples of per-repository customization:

• Different LLM providers or models
• Different commit message languages
• Different writing styles or tones
• Emojis enabled or disabled per project

To create a repository-specific configuration:

cp ~/.config/cai/cai_config.yml .

Modify the copied file as needed. As an alternative execute:

git cai -g

Available configuration options

• default – default LLM provider
• model – model to use for the selected provider
  (note: not all models may be compatible)
• temperature – controls how creative the generated messages are
• language – language used for commit messages
• style – tone or style of the commit message
• emoji – enable or disable emojis
• load_tokens_from – path to the file where API tokens are stored
• prompt_file - path to the file where the prompt for the commit is stored
• squash_prompt_file - path to the file where the prompt for the squash is stored
• branch_context – include current branch name as LLM context (default: false)
• conventional – use Conventional Commits format (default: false)
• token_logging – log token usage after each LLM call (default: true for new installs)
• measure_time – log generation time (default: false)

---

CLI

In addition to git cai, the following options are available:

• -A, --amend – regenerate and amend the last commit message
• -a, --all – stage all tracked modified and deleted files
• -b, --branch – include current branch name as context for the LLM
• -C, --conventional – use Conventional Commits format (type(scope): description)
• -c, --crazy – Trust the LLM and commit without checking
• -d, --debug – enable debug logging
• -g, --generate-config – generate the default cai_config.yml in the current directory
• -H, --set-home – set a config value in home config (key=value), always targets ~/.config/cai/
• -h, --help – show help and available commands
• -i, --install-completion – install shell completion for bash, zsh, or fish
• -l, --list – list available information (config, editor, language, model, path, provider, style)
• -m, --model – override the model for this invocation (requires -P)
• -p, --generate-prompts – generate default commit_prompt.md and squash_prompt.md in the current directory (for customization)
• -P, --provider – override the LLM provider for this invocation
• -S, --set – set a config value (key=value) in repo config (requires existing repo config)
• -H, --set-home – set a config value in home config (key=value), always targets ~/.config/cai/
• -s, --squash [N|HASH] – squash commits on the current branch and summarize them. Without argument: squash all since branch checkout. With a number: squash the last N commits. With a commit hash: squash up to and including that commit
• -t, --time – measure and log commit message generation time
• -x, --context – provide extra context for the LLM (e.g. ticket number, reason for change)
• -u, --update – check for updates
• -v, --version – show the installed version

Amend

To regenerate the last commit message and amend it:

git cai -A

This reads the diff from the most recent commit, sends it to the LLM, and opens the editor for review. Use with -c to amend immediately without the editor: git cai -A -c.

Conventional Commits

To generate commit messages in Conventional Commits format:

git cai -C

This enforces the type(scope): description structure. Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert. Use ! after the type/scope for breaking changes.

To enable it permanently:

git cai -S conventional=true

Changing configuration from the CLI

Instead of editing YAML files manually, use --set or --set-home to update config values.

--set (-S) targets the repo config (requires an existing cai_config.yml in the repo root):

git cai -S default=anthropic           # change the default provider
git cai -S emoji=false                  # disable emojis
git cai -S groq.model=llama-3.3-70b    # nested key (dot notation)
git cai -S openai.temperature=0.7      # set temperature as float

If no repo config exists, an error is shown. Use git cai -g to create one first.

--set-home (-H) always targets the home (default) config (~/.config/cai/):

git cai -H language=de
git cai -H emoji=false

---

License

This project is licensed under the MIT License.