aicommit2
A Reactive CLI that generates commit messages for Git, YADM, and Jujutsu with Ollama, ChatGPT, Gemini, Claude, Mistral, and other AI
Table of Contents
Quick start
# Install via Homebrew (macOS/Linux)
brew install aicommit2
# Or install via npm
npm install -g aicommit2
# Set up AI providers (interactive wizard)
aicommit2 setup
# Or configure manually
aicommit2 config set OPENAI.key=<your-key>
# Use in your Git repository
git add .
aicommit2
# Also works with YADM and Jujutsu repositories (auto-detected)
yadm add <file>
aicommit2
Introduction
aicommit2 automatically generates commit messages using AI. It supports Git, YADM (Yet Another Dotfiles Manager), and Jujutsu (jj) repositories with automatic detection. AICommits inspired the core functionalities and architecture of this project.
Key features
- VCS Support: Works with Git, YADM, and Jujutsu repositories
- Multi-AI Support: Integrates with OpenAI, Anthropic Claude, Google Gemini, Mistral AI, Cohere, Groq, Ollama and more
- OpenAI API Compatibility: Support for any service that implements the OpenAI API specification
- Reactive CLI: Enables simultaneous requests to multiple AIs and selection of the best commit message
- Code Review: AI-powered structured code review with severity levels before committing
- Commit Rewrite: Rewrite the commit message of any existing commit with AI (
aicommit2 rewrite)
- Git Hook Integration: Can be used as a prepare-commit-msg hook
- Custom Prompt: Supports user-defined system prompt templates
- Diff Compression: Reduces token usage by 30-60% with smart diff compression
Supported Providers
| Provider |
Default Model |
Documentation |
| OpenAI |
gpt-4o-mini |
Guide |
| Copilot SDK (Preview) |
gpt-4.1 |
Guide |
| Claude Code (Preview) |
sonnet |
Guide |
| Gemini CLI (Preview) |
(CLI default) |
Guide |
| OpenRouter |
openrouter/auto |
Guide |
| Anthropic |
claude-sonnet-4-20250514 |
Guide |
| Gemini |
gemini-3-flash-preview |
Guide |
| Mistral |
mistral-small-latest |
Guide |
| Codestral |
codestral-latest |
Guide |
| Cohere |
command-a-03-2025 |
Guide |
| Groq |
llama-3.3-70b-versatile |
Guide |
| Perplexity |
sonar |
Guide |
| DeepSeek |
deepseek-v4-flash |
Guide |
| GitHub Models |
openai/gpt-4o-mini |
Guide |
| Bedrock |
anthropic.claude-haiku-4-5-20251001-v1:0 |
Guide |
| Ollama |
(user configured) |
Guide |
📘 For OpenAI-compatible APIs, see Compatibility Guide
📘 GitHub note: COPILOT_SDK uses Copilot CLI authentication (Copilot Requests permission), while GITHUB_MODELS uses GitHub Models API tokens (models: read).
📘 Copilot SDK stable setup example (config.ini + env): Copilot SDK Guide.
📘 Claude Code note: CLAUDE_CODE runs your locally installed Claude Code CLI with your Claude subscription (Pro/Max) — no API key. It is meant for terminal usage of aicommit2; it is not intended to be called from inside a Claude Code agent session. See Claude Code Guide.
📘 Gemini CLI note: GEMINI_CLI runs your locally installed Gemini CLI with your Gemini login (free tier or subscription) — no API key. It is the subscription counterpart to the API-key GEMINI provider. See Gemini CLI Guide.
Setup
- Install aicommit2:
Via Homebrew (recommended for macOS/Linux):
brew install aicommit2
Via npm:
npm install -g aicommit2
⚠️ For npm installation, the minimum supported version of Node.js is v18. Check your Node.js version with node --version.
Git 2.13 or later is required (for .gitattributes-aware diff filtering).
⚠️ Homebrew installation does not include Copilot SDK support due to its proprietary dependency. Use npm if you need Copilot SDK.
- Configure your AI provider(s) (at least ONE provider must be configured):
Option A: Interactive setup wizard (recommended)
aicommit2 setup
👉 The setup wizard guides you through provider selection, API key entry, and model configuration in one step.
Option B: Manual configuration
aicommit2 config set OPENAI.key=<your key>
aicommit2 config set ANTHROPIC.key=<your key>
# ... (similar commands for other providers)
- Run aicommit2 in your Git or Jujutsu repository:
# For Git repositories
git add <files...>
aicommit2
# Works with Jujutsu too (auto-detected, no staging needed)
aicommit2
👉 Tip: Use the aic2 alias if aicommit2 is too long for you.
Alternative Installation Methods
Nix Installation
If you use the Nix package manager, aicommit2 can be installed directly using the provided flake:
# Install temporarily in your current shell
nix run github:tak-bro/aicommit2
# Install permanently to your profile
nix profile install github:tak-bro/aicommit2
# Use the shorter alias
nix run github:tak-bro/aic2 -- --help
Using in a Flake-based Project
Add aicommit2 to your flake inputs:
{
# flake.nix configuration file
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
aicommit2.url = "github:tak-bro/aicommit2";
};
# Rest of your flake.nix file
}
# Somewhere where you define your packages
{pkgs, inputs, ...}:{
environment.systemPackages = [inputs.aicommit2.packages.x86_64-linux.default];
# Or home packages
home.packages = [inputs.aicommit2.packages.x86_64-linux.default];
}
Development Environment
To enter a development shell with all dependencies:
nix develop github:tak-bro/aicommit2
After setting up with Nix, you’ll still need to configure API keys as described in the Setup section.
From Source
git clone https://github.com/tak-bro/aicommit2.git
cd aicommit2
npm run build
npm install -g .
Via VSCode Devcontainer
Add feature to
your devcontainer.json file:
"features": {
"ghcr.io/kvokka/features/aicommit2:1": {}
}
How it works
This CLI tool runs git diff to grab all your latest code changes, sends them to configured AI, then returns the AI generated commit message.
If the diff becomes too large, AI will not function properly. If you encounter an error saying the message is too long or it’s not a valid commit message, try reducing the commit unit.
Version Control Systems
Git (Primary)
# Standard Git workflow
git add <files>
aicommit2
- Uses
git diff --cached for staged changes
- Supports all Git features and hooks
- Requires staging changes before commit
YADM Support
aicommit2 supports YADM (Yet Another Dotfiles Manager) for managing dotfiles:
# Standard YADM workflow
yadm add <files>
aicommit2
Features:
- Automatic detection of YADM repositories (prioritized before Git)
- Uses
yadm commands instead of git for all operations
- Supports all YADM features including encryption and alternate files
- Works with dotfiles in
$HOME directory
- Hook installation:
aicommit2 hook install (installs to ~/.config/yadm/hooks/)
- Note: Watch mode (
--watch-commit) is not supported for YADM repositories
Installation:
# macOS
brew install yadm
# Linux
apt-get install yadm # Debian/Ubuntu
dnf install yadm # Fedora
# Initialize repository
yadm init
# or clone existing dotfiles
yadm clone <url>
Jujutsu Support
aicommit2 also supports Jujutsu (jj) repositories:
# Automatic jj detection (no staging needed)
aicommit2
# Force Git when both .jj and .git exist (for colocated repos)
FORCE_GIT=true aicommit2
# or
aicommit2 config set forceGit=true
Features:
- Automatic detection of
.jj repositories (prioritized over Git since jj v0.34.0+ uses colocated repos)
- Uses
jj describe to set commit message (does NOT run jj new by default)
- Supports Jujutsu’s fileset syntax for file exclusions
- Works seamlessly with colocated Git repositories
jj new Behavior:
By default, aicommit2 only runs jj describe to set the commit message, without creating a new changeset. This matches the workflow of many Jujutsu users who prefer to manually control when to run jj new.
To automatically run jj new after describing (mimics jj commit behavior):
# Via CLI flag
aicommit2 --jj-auto-new
# Or via config (persistent)
aicommit2 config set jjAutoNew=true
Installation:
# macOS
brew install jj
# Linux/Windows
cargo install jj-cli
# Initialize repository
jj init
Detection Priority
- CLI flags (highest priority - overrides everything):
--git: Force use Git--yadm: Force use YADM--jj: Force use Jujutsu
- Environment variables:
FORCE_GIT=true: Forces GitFORCE_YADM=true: Forces YADMFORCE_JJ=true: Forces Jujutsu
- Config:
aicommit2 config set forceGit=true (forces Git)
- Auto-detection:
- Jujutsu repository (checked first - since jj v0.34.0+, repos are colocated with .git)
- Git repository (checked for .git directories - regular Git repos)
- YADM repository (checked last - for dotfiles in $HOME without .git directory)
Force VCS Selection
Sometimes you may want to use a specific VCS even when multiple are available:
# Use YADM in a directory that has both .git and YADM tracking
cd ~/my-project # Has .git directory
aicommit2 --yadm # Forces YADM usage instead of Git
# Use Git explicitly
aicommit2 --git
# Use Jujutsu explicitly
aicommit2 --jj
Usage
CLI mode
You can call aicommit2 directly to generate a commit message for your staged changes:
git add <files...>
aicommit2
aicommit2 passes down unknown flags to git commit, so you can pass in commit flags.
For example, you can stage all changes in tracked files as you commit:
aicommit2 --all # or -a
CLI Options
Run aicommit2 --help to see all available options grouped by category.
Message Options
--locale or -l: Locale to use for the generated commit messages (default: en)--generate or -g: Number of messages to generate (default: 1)
- Warning: This uses more tokens, meaning it costs more.
--type or -t: Git commit message format (default: conventional). It supports conventional and gitmoji--prompt or -p: Custom prompt to fine-tune the AI generation--include-body or -i: Force include commit body in all generated messages (default: false)
Behavior
After you pick a message, Use selected message? (Ynerh) takes one key: y (or Enter) commits, n cancels (exit 1), e opens $VISUAL/$EDITOR and commits the result, r asks the providers again and shows a new picker (the code review is not repeated), and h lists the keys. aicommit2 rewrite asks with the same keys; there, n or declining the “already pushed” warning exits 1 and leaves the commit unchanged.
If the commit then fails (for example, a pre-commit hook rejects it), aicommit2 asks Commit failed. Retry? (Rqh): fix the problem in another terminal and press r to commit the same message again, or q to quit (exit 1). With Git and YADM the message is saved before the commit runs its hooks, so aicommit2 --retry works later too, even after Ctrl-C during a slow hook; if the save itself fails, a warning says so and the quit option reads the message is not saved. The saved message is removed once a commit succeeds. One gap remains: Ctrl-C after git has recorded the commit (for example, during a slow post-commit hook) can leave it behind, and a later aicommit2 --retry would commit it again, so delete .git/AICOMMIT2_MSG in that case.
If stdin closes while any of these prompts waits for an answer (for example aicommit2 < /dev/null), aicommit2 prints Input closed before the prompt was answered and exits 1 without committing. Use --auto-select (-s) for runs that have no one to answer: --confirm skips only the final confirmation, not the message picker.
--all or -a: Automatically stage changes in tracked files for the commit, like git commit -a. Untracked (new) files are not staged and are listed on stderr; git add them first or use --add-all (default: false)--add-all or -A: Stage all changes, including untracked files, like git add -A. .gitignore still applies; files matched by --exclude are staged and committed too, only left out of the AI analysis. Staging happens before messages are generated, so the files stay staged even with --dry-run or when you cancel. Git only: YADM’s work tree is $HOME, so it exits with an error there (default: false)--confirm or -y: Skip confirmation when committing after message generation (default: false)--auto-select or -s: Automatically select the first successfully generated message (default: false)
- Runs non-interactively: skips both the message picker and the commit confirmation, regardless of how many AI providers are configured
- With
codeReview enabled, the first review is printed in full instead of opening the review list. Critical findings are printed as a warning and the run continues, since there is no prompt to answer
--edit or -e: Open the AI-generated commit message in your default editor (default: false)--clipboard or -c: Copy the selected message to clipboard and exit without committing (default: false)--dry-run or -d: Generate commit message without committing (default: false). When stdout is piped or captured, the first message is picked without prompting and only the message is written to stdout (everything else goes to stderr)
- Useful for reviewing messages before manual commit (e.g., with GitHub Desktop)
--output or -o: Output format for non-interactive mode (default: none)
- Use
--output json for LazyGit integration
VCS Selection
--git: Force use Git (overrides auto-detection)--yadm: Force use YADM (overrides auto-detection)--jj: Force use Jujutsu (overrides auto-detection)--jj-auto-new: Run jj new after jj describe (default: false)
Hook Integration
--exclude or -x: Files to exclude from AI analysis. They are still staged and committed--include-generated: Also send generated-file diffs (default: false; lockfiles always stay name-only). By default, lockfiles, *.min.js, *.min.css, *.map, *.snap, and files marked linguist-generated in .gitattributes are listed by name only, and shown as (diff omitted) in the staged file list--disable-lowercase: Preserve original casing of commit messages (default: false)--retry: Commit the message a failed commit saved (for example, after a pre-commit hook fails), without generating a new one. Unknown flags are passed to git commit, so aicommit2 --retry --no-verify works. It always commits, so it refuses --dry-run and --clipboard--verbose or -v: Enable verbose logging for debugging (default: false)
Examples:
# Generate multiple commit messages with clipboard and file exclusions
aicommit2 --locale "jp" --all --type "conventional" --generate 3 --clipboard --exclude "*.json" --exclude "*.ts"
# Generate and edit a commit message
aicommit2 --edit --type conventional # or gitmoji
# Generate message without committing (dry-run)
aicommit2 --dry-run # or -d
# Capture the message in a script (no prompt, message only on stdout)
git commit -m "$(aicommit2 -d)"
# A pre-commit hook failed: fix the issue, then commit the saved message again
aicommit2 --retry
# Dry-run with clipboard (generate, select, then copy)
aicommit2 -d -c
# Enable verbose logging for debugging
aicommit2 --verbose # or -v
Commands
In addition to the main commit message generation, aicommit2 provides several utility commands:
| Command |
Description |
aicommit2 setup |
Interactive setup wizard for configuring AI providers |
aicommit2 setup lazygit |
Set up the LazyGit integration |
aicommit2 config |
Manage configuration (get, set, list, del) |
aicommit2 doctor |
Check health status of AI providers, integrations and the installed version |
aicommit2 stats |
View usage statistics and performance metrics |
aicommit2 rewrite |
Rewrite the commit message of any commit using AI |
aicommit2 hook |
Install/uninstall Git prepare-commit-msg hook |
aicommit2 log |
Manage log files |
aicommit2 github-login |
Login to GitHub for GitHub Models access |
# Interactive setup wizard
aicommit2 setup
# Configuration management
aicommit2 config set OPENAI.key=<your-key>
aicommit2 config get OPENAI
aicommit2 config list
# Health check
aicommit2 doctor
# Statistics
aicommit2 stats
aicommit2 stats -d 7 # Last 7 days
aicommit2 stats clear # Clear all stats
# Git hook
aicommit2 hook install
aicommit2 hook uninstall
# Rewrite commit message
aicommit2 rewrite # Rewrite HEAD commit message
aicommit2 rewrite abc1234 # Rewrite specific commit
aicommit2 rewrite HEAD~2 --dry-run # Preview without rewriting
aicommit2 rewrite -i # Include the commit body in the rewritten message
GitHub Models tip: use aicommit2 github-login and set GITHUB_MODELS.model in publisher/model format (for example, openai/gpt-5).
Integrations
LazyGit
aicommit2 integrates with LazyGit so you can generate commit messages without leaving the LazyGit UI.
Quick Setup
aicommit2 setup lazygit
This detects your LazyGit config file, backs it up, and adds a custom command. Then in LazyGit:
- Stage your changes
- Press
c in the Files panel — the full aicommit2 UI opens (multi-provider streaming)
- Select a message to commit
Options:
--key <key> — use a different keybinding (default: c, which overrides LazyGit’s default commit key)--mode fzf — install the fzf-based picker with subject + body preview instead (requires jq and fzf; bound to C by default)--force — overwrite an existing aicommit2 integration
Manual Setup
Add the following to your LazyGit config file (~/.config/lazygit/config.yml or ~/Library/Application Support/lazygit/config.yml on macOS):
customCommands:
- key: "c"
context: "files"
description: "Generate commit message with aicommit2"
command: "aicommit2"
output: terminal
This runs the full aicommit2 interactive UI in a terminal — streaming, multi-provider, no output parsing involved.
Note: This overrides LazyGit’s default c (commit) key. You can change the key to another value (e.g., <c-a>) if you prefer to keep the default behavior.
Advanced: JSON Output (menuFromCommand)
Use the --output json flag to get AI-generated commit messages in JSON Lines format:
aicommit2 --output json
# Output: {"subject":"feat: add user authentication","body":""}
# Output: {"subject":"fix: resolve login bug","body":"Fixes issue with session handling"}
Each line is a separate JSON object with subject and body fields, compatible with LazyGit’s menuFromCommand prompt type. On failure, an {"error":"..."} object is written to stdout and a readable message to stderr (exit code 1).
customCommands:
# Quick commit with AI-generated subject (c in files panel)
- key: "c"
context: "files"
description: "Generate commit message with aicommit2"
prompts:
- type: "menuFromCommand"
title: "Select commit message"
key: "Commit"
command: "aicommit2 --output json"
filter: '"subject":"(?P<subject>[^"]+)","body":"(?P<body>[^"]*)"'
valueFormat: '{{ .subject }}<SEP>{{ .body }}'
labelFormat: '{{ .subject }}'
output: "terminal"
command: bash -c 'MSG="{{ .Form.Commit }}" && SUBJ="${MSG%%<SEP>*}" && BODY="${MSG#*<SEP>}" && git commit -e -m "$SUBJ" ${BODY:+-m "$BODY"}'
Warning: The regex filter cannot handle subjects containing double quotes, and multi-line bodies arrive as escaped \n sequences. Prefer the Quick Setup recipe above, or the fzf variant below for messages with bodies.
Advanced: fzf Preview with Body
For detailed commit messages with subject + body, use the fzf-based approach. This uses --include-body (-i) flag to generate detailed body content and shows a preview window before committing.
Tip: aicommit2 setup lazygit --mode fzf installs the script and config entry automatically. The steps below are for manual setup.
Requirements: jq and fzf must be installed (brew install jq fzf).
First, create the script file at ~/.config/lazygit/scripts/aicommit_fzf.sh (or ~/Library/Application Support/lazygit/scripts/ on macOS):
#!/usr/bin/env bash
set -euo pipefail
for cmd in aicommit2 jq fzf; do
if ! command -v "$cmd" >/dev/null 2>&1; then
echo "$cmd is required"
exit 1
fi
done
results_file="$(mktemp -t lazygit-aicommit-results.XXXXXX)"
trap 'rm -f "$results_file"' EXIT INT TERM
selected="$(
echo | fzf \
--prompt="AI commit> " \
--header="Select a message" \
--height=100% \
--layout=reverse \
--info=inline \
--with-nth=2.. \
--delimiter=$'\t' \
--with-shell="bash --noprofile --norc -c" \
--preview-window="right:60%:wrap" \
--preview "jq -r '.[ {1} ] | \"\(.subject)\n\n\(.body)\"' $results_file" \
--bind "load:unbind(load)+reload-sync#aicommit2 -i --output json 2>/dev/null | jq -s '.' > $results_file && jq -r 'to_entries[] | \"\\(.key)\\t\\(.value.subject)\"' $results_file#"
)" || exit 0
[ -n "$selected" ] || exit 0
index="${selected%%$'\t'*}"
subject="$(jq -r ".[$index].subject" "$results_file")"
body="$(jq -r ".[$index].body" "$results_file")"
git commit -e -m "$subject" -m "$body"
Make it executable: chmod +x ~/.config/lazygit/scripts/aicommit_fzf.sh
Then add this to your LazyGit config:
customCommands:
# Long commit with fzf preview (Shift+C in files panel)
- key: "C"
context: "files"
description: "Generate commit message (long) with aicommit2"
output: "terminal"
command: "/path/to/aicommit_fzf.sh" # Update with your script path
Thanks to @peinan for this configuration! See the original discussion and dotfiles (config.yml, aicommit_fzf.sh) for reference.
Git Hooks
You can integrate aicommit2 with Git via the prepare-commit-msg hook. This lets you use Git like you normally would, and edit the commit message before committing.
Automatic Installation
In the Git repository you want to install the hook in:
aicommit2 hook install
The hook location is resolved by Git itself, so linked worktrees (git worktree add) and a custom core.hooksPath are supported.
Manual Installation
If you prefer to set up the hook manually, create or edit the .git/hooks/prepare-commit-msg file:
#!/bin/sh
# your-other-hook "$@"
aicommit2 --hook-mode "$@"
Make the hook executable:
chmod +x .git/hooks/prepare-commit-msg
Use with a custom core.hooksPath
If you are using husky or have configured a custom core.hooksPath, update the corresponding hooks file instead. For Husky users, this file is .husky/prepare-commit-message.
Integration with pre-commit Framework
If you’re using the pre-commit framework, you can add aicommit2 to your .pre-commit-config.yaml:
repos:
- repo: local
hooks:
- id: aicommit2
name: AI Commit Message Generator
entry: aicommit2 --pre-commit
language: node
stages: [prepare-commit-msg]
always_run: true
Make sure you have:
- Installed pre-commit:
brew install pre-commit
- Installed aicommit2 globally:
npm install -g aicommit2
- Run
pre-commit install --hook-type prepare-commit-msg to set up the hook
Note: The --pre-commit flag is specifically designed for use with the pre-commit framework and ensures proper integration with other pre-commit hooks.
Uninstall
In the Git repository you want to uninstall the hook from:
aicommit2 hook uninstall
Or manually delete the .git/hooks/prepare-commit-msg file.
Health Check
Use the doctor command to check the status of your configured AI providers and integrations:
aicommit2 doctor
Example output:
🩺 aicommit2 Health Check
Providers:
✅ OPENAI API key configured
✅ OLLAMA Running (Host: http://localhost:11434)
⏭️ ANTHROPIC Not configured
⚠️ GEMINI API key configured
Integrations:
✅ LAZYGIT Integration configured (~/.config/lazygit/config.yml)
Summary: 3 healthy, 0 error, 1 warning, 1 skipped
Status icons:
- ✅ Healthy: Provider is properly configured
- ⚠️ Warning: Provider has issues (e.g., Ollama not running)
- ❌ Error: Provider configuration has errors
- ⏭️ Skipped: Provider is not configured
Statistics
Use the stats command to view AI request statistics and performance metrics:
aicommit2 stats
Example output:
📊 aicommit2 Statistics
Period: 3/16/2026 - 3/17/2026
Overview:
Total requests: 144
Success rate: 60.4%
Avg response time: 1.3s
Provider Usage:
Provider Rate Bar Cnt Selected Time
GROQ 100% ████████████████████ 48 1 (2.1%) 732ms
OPENAI 0% ░░░░░░░░░░░░░░░░░░░░ 46 0 514ms
GITHUB_MODELS 96% ███████████████████░ 25 0 2.0s
GEMINI 29% ██████░░░░░░░░░░░░░░ 14 0 2.8s
Columns:
- Rate: Success rate (bar color: 🟢 ≥80%, 🟡 50-79%, 🔴 <50%)
- Cnt: Total request count
- Selected: How many times you chose this provider’s message
Options:
aicommit2 stats -d 7 - Show statistics for the last 7 daysaicommit2 stats clear - Clear all statistics
Statistics are stored locally at ~/.config/aicommit2/stats.json. Use aicommit2 stats clear to reset.
Configuration
aicommit2 supports configuration via command-line arguments, environment variables, and a configuration file. Settings are resolved in the following order of precedence:
- Command-line arguments
- Environment variables
- Configuration file
- Default values
Configuration File Location
aicommit2 follows the XDG Base Directory Specification for its configuration file. The configuration file is named config.ini and is in INI format. It is resolved in the following order of precedence:
AICOMMIT_CONFIG_PATH environment variable: If this environment variable is set, its value is used as the direct path to the configuration file.$XDG_CONFIG_HOME/aicommit2/config.ini: This is the primary XDG-compliant location. If $XDG_CONFIG_HOME is not set, it defaults to ~/.config/aicommit2/config.ini.~/.aicommit2: This is a legacy location maintained for backward compatibility.
The first existing file found in this order will be used. If no configuration file is found, aicommit2 will default to creating a new config.ini file in the $XDG_CONFIG_HOME/aicommit2/ directory.
You can find the path of the currently loaded configuration file using the config path command:
aicommit2 config path
When a project config file is found (see below), config path still prints the global path on stdout and names the project file on stderr, so $(aicommit2 config path) keeps pointing at the writable global file.
Project Configuration
A repository can carry its own settings in .aicommit2/config.ini. aicommit2 looks for it from the current directory up to the repository root (the first directory containing .git or .jj); outside a repository only the current directory is checked. The first file found is layered over the global config section by section, so a project key replaces the global key of the same section and every other key keeps its global value:
- Command-line arguments
- Environment variables
- Project config (
.aicommit2/config.ini)
- Global config file
- Default values
# .aicommit2/config.ini
locale=ko
type=conventional
systemPromptPath=prompts/commit.txt
providers=OLLAMA
[OLLAMA]
model=qwen2.5-coder
Because the file comes from whoever wrote the repository, only content and shape settings are read from it: locale, generate, type, maxLength, includeBody, systemPrompt, systemPromptPath, codeReviewPromptPath, exclude, excludeGenerated, model (per provider), temperature, topP, maxTokens, timeout, codeReview, disabled, stream, disableLowerCase, ticketExtraction, learnConventions, diffCompression, maxHunkLines, maxDiffLines, diffContext and providers. Everything else is ignored with a one-line warning on stderr, including:
- API keys,
envKey, url, path, host and other endpoint or authentication settings, so a cloned repository cannot send your keys elsewhere
- sections for providers that are neither built in nor defined in your global config
disabled=false, so a repository cannot re-enable a provider you disabled- a top-level
model, and a provider model for OLLAMA, CLAUDE_CODE, GEMINI_CLI, COPILOT_SDK or BEDROCK unless your global config already sets a model for it, so a repository cannot turn a provider on
- a provider
model listing more than one model or starting with -; a repository picks one model per provider, so it cannot fan out billed requests on your key
systemPromptPath/codeReviewPromptPath that are absolute or resolve (symlinks followed) outside the .aicommit2/ directory; relative paths resolve against that directory, so .git/config or an untracked .env cannot reach the prompt- the whole file when
.aicommit2/ is a symlink, or .aicommit2/config.ini resolves outside the repository
$VAR/${VAR} is not expanded in the project file. config set, config add, config list and config validate keep working on the global file only.
Restricting providers
providers limits the providers aicommit2 may use to a comma-separated list. In a project file it lets an air-gapped repository stay on local models:
providers=OLLAMA
Only listed providers that are otherwise configured run. When both the global and the project config set providers, the project list is intersected with the global one, so a repository can narrow the set but never add a provider back.
Environment Variable Expansion in Config File
You can use environment variables in your configuration file values. Both $VAR and ${VAR} syntax are supported.
Example config.ini:
[OPENAI]
key=$OPENAI_API_KEY
url=${CUSTOM_API_URL}/v1
OpenRouter example:
logging=true
generate=1
locale=ru
maxTokens=4096
temperature=0.2
[OPENROUTER]
envKey=OPENROUTER_BASE_TOKEN
model=stepfun/step-3.5-flash:free
url=https://openrouter.ai
path=/api/v1/chat/completions
systemPromptPath=prompts/aicommit_prompt.txt
responseFormat.type=json_object
provider.allow_fallbacks=true
provider.require_parameters=false
If systemPromptPath is relative, it is resolved relative to the config file
location.
Nested OpenRouter objects such as responseFormat and provider can be written
directly in config.ini using dotted keys, or set with JSON via aicommit2 config set.
Reading and Setting Configuration
- READ:
aicommit2 config get [<key> [<key> ...]]
- SET:
aicommit2 config set <key>=<value>
- DELETE:
aicommit2 config del <config-name>
- VALIDATE:
aicommit2 config validate
Example:
# Get all configurations
aicommit2 config get
# Get specific configuration
aicommit2 config get OPENAI
aicommit2 config get GEMINI.key
# Set configurations
aicommit2 config set OPENAI.generate=3 GEMINI.temperature=0.5
# Delete a configuration setting or section
aicommit2 config del OPENAI.key
aicommit2 config del GEMINI
aicommit2 config del timeout
# Check the configuration file
aicommit2 config validate
Validating the Configuration
A hand-edited config.ini can contain mistakes that a normal run stays silent about: a
section whose name is not uppercase is dropped entirely, and an option no provider
accepts is ignored. aicommit2 config validate reports them together with any invalid
values, and exits with a non-zero status when it finds an error. Values are checked after
environment variable expansion, so run it in the same environment your commits run in:
Config file: ~/.config/aicommit2/config.ini
✖ [openai]: Invalid section name, so the whole section is ignored. Names must be uppercase letters, numbers and underscores. Did you mean [OPENAI]?
! OPENAI.modell: Unknown option, silently ignored. Did you mean `model`?
✖ OPENAI.temperature: Invalid config property temperature: Must be decimal between 0 and 2
2 error(s), 1 warning(s)
Environment Variables
You can configure API keys using environment variables. This is particularly useful for CI/CD environments or when you don’t want to store keys in the configuration file.
# OpenAI
OPENAI_API_KEY="your-openai-key"
# Anthropic
ANTHROPIC_API_KEY="your-anthropic-key"
# Google
GEMINI_API_KEY="your-gemini-key"
# Mistral AI
MISTRAL_API_KEY="your-mistral-key"
CODESTRAL_API_KEY="your-codestral-key"
# Other Providers
COHERE_API_KEY="your-cohere-key"
GROQ_API_KEY="your-groq-key"
PERPLEXITY_API_KEY="your-perplexity-key"
DEEPSEEK_API_KEY="your-deepseek-key"
Note: You can customize the environment variable name used for the API key with the envKey configuration property for each service.
Usage Example:
OPENAI_API_KEY="your-openai-key" ANTHROPIC_API_KEY="your-anthropic-key" aicommit2
Note: Environment variables take precedence over configuration file settings.
aicommit2 offers flexible configuration options for all AI services, including support for specifying multiple models. You can configure settings via command-line arguments, environment variables, or a configuration file.
-
Command-line arguments: Use the format --[Model].[Key]=value.
To specify multiple models, use the --[Model].model=model1,model2 format.
aicommit2 --OPENAI.locale="jp" --GEMINI.temperature="0.5" --OPENAI.model="gpt-4o-mini,gpt-3.5-turbo"
-
Configuration file: Refer to Configuration File Location or use the set command.
For array-like values like model, you can use either the model=model1,model2 comma-separated syntax or the model[]= syntax for multiple entries. This applies to all AI services.
# General Settings
logging=true
generate=2
temperature=1.0
# Model-Specific Settings
[OPENAI]
key="<your-api-key>"
temperature=0.8
generate=1
model="gpt-4o-mini,gpt-3.5-turbo"
systemPromptPath="<your-prompt-path>"
[GEMINI]
key="<your-api-key>"
generate=5
includeBody=true
model="gemini-3-flash-preview,gemini-3.1-pro-preview"
[OLLAMA]
temperature=0.7
model[]=llama3.2
model[]=codestral
The priority of settings is: Command-line Arguments > Environment Variables > Model-Specific Settings > General Settings > Default Values.
Configuration Examples
aicommit2 config set \
generate=2 \
topP=0.8 \
maxTokens=1024 \
temperature=0.7 \
OPENAI.key="sk-..." OPENAI.model="gpt-4o-mini" OPENAI.temperature=0.5 \
ANTHROPIC.key="sk-..." ANTHROPIC.model="claude-sonnet-4-20250514" ANTHROPIC.maxTokens=2000 \
MISTRAL.key="your-key" MISTRAL.model="mistral-small-latest" \
OLLAMA.model="llama3.2" OLLAMA.numCtx=4096 OLLAMA.watchMode=true
🔍 Detailed Support Info: Check each provider’s documentation for specific limits and behaviors:
General Settings
For detailed information about all available settings, see the General Settings documentation.
| Setting |
Description |
Default |
locale |
Locale for the generated commit messages |
en |
generate |
Number of commit messages to generate |
1 |
type |
Type of commit message (conventional / gitmoji) |
conventional |
maxLength |
Maximum character length of the commit subject |
50 |
timeout |
Request timeout (milliseconds) |
10000 |
temperature |
Model’s creativity (0.0 - 2.0) |
0.7 |
maxTokens |
Maximum number of tokens to generate |
1024 |
includeBody |
Whether the commit message includes body |
false |
codeReview |
Enable automated code review before commit |
false |
codeReviewPromptPath |
Path to custom code review prompt file |
- |
autoCopy |
Auto-copy commit message to clipboard (commits normally) |
false |
useStats |
Enable usage statistics tracking |
true |
excludeGenerated |
Send lockfile/generated files by name only, without their diff |
true |
statsDays |
Days to retain statistics data (auto-cleanup) |
30 |
systemPromptPath |
Path to custom system prompt file |
- |
modelNameDisplay |
Model name display in CLI labels (none / short / full) |
short |
stream |
Experimental. Enable streaming for real-time commit message generation |
false |
diffCompression |
Diff compression mode (auto / compact / none) |
auto |
maxHunkLines |
Max lines per hunk in compressed diff (0 = unlimited) |
0 |
maxDiffLines |
Max total lines in compressed diff (0 = unlimited) |
0 |
diffContext |
Number of context lines in git diff (0-10) |
3 |
# Example: Set settings for a specific model
aicommit2 config set OPENAI.locale="jp"
aicommit2 config set GEMINI.temperature=0.5
aicommit2 config set ANTHROPIC.includeBody=true
👉 For all settings and detailed explanations, see docs/settings.md
Available Settings by Model
|
timeout |
temperature |
maxTokens |
topP |
stream |
| OpenAI |
✓ |
✓ |
✓ |
✓ |
✓ |
| Anthropic Claude |
✓ |
✓ |
✓ |
✓ |
✓ |
| Gemini |
|
✓ |
✓ |
✓ |
✓ |
| Mistral AI |
✓ |
✓ |
✓ |
✓ |
|
| Codestral |
✓ |
✓ |
✓ |
✓ |
|
| Cohere |
✓ |
✓ |
✓ |
✓ |
|
| Groq |
✓ |
✓ |
✓ |
✓ |
✓ |
| Perplexity |
✓ |
✓ |
✓ |
✓ |
|
| DeepSeek |
✓ |
✓ |
✓ |
✓ |
✓ |
| Github Models |
✓ |
✓ |
✓ |
✓ |
|
| Ollama |
✓ |
✓ |
|
✓ |
✓ |
| OpenAI API-Compatible |
✓ |
✓ |
✓ |
✓ |
✓ |
Diff Compression
aicommit2 can compress git diffs before sending to AI providers, reducing token usage by 30-60%. Inspired by RTK’s token optimization techniques.
When compressing (compact mode, or auto mode on a large diff), the compressor:
- Strips diff metadata headers (
diff --git, index, ---/+++)
- Minimizes context lines (keeps only lines adjacent to changes, replaces distant context with
...)
- Caps large hunks and total diff size to protect model context windows
The default auto mode sends diffs under 100 KB untouched and compresses larger ones with a 150-line hunk cap and a 3,000-line total cap (unless you set maxHunkLines / maxDiffLines yourself), so a big staged change no longer fails at the provider.
# Always compress, regardless of diff size
aicommit2 config set diffCompression=compact
# Or per model — useful for models with smaller context windows
aicommit2 config set OLLAMA.diffCompression=compact
aicommit2 config set OLLAMA.maxHunkLines=100
aicommit2 config set OLLAMA.maxDiffLines=500
# Tune compression settings
aicommit2 config set maxHunkLines=200 # max lines per hunk (0=unlimited)
aicommit2 config set maxDiffLines=1000 # max total diff lines (0=unlimited)
aicommit2 config set diffContext=1 # reduce git context lines (default: 3)
# Restore the default (compress only large diffs)
aicommit2 config set diffCompression=auto
# Never compress, even for large diffs (behavior of versions before auto mode)
aicommit2 config set diffCompression=none
Logging
The application utilizes two distinct logging systems to provide comprehensive insights into its operations:
1. Application Logging (Winston)
This system handles general application logs and exceptions. Its behavior can be configured through the following settings in your config.ini file:
-
logLevel:
- Description: Specifies the minimum level for logs to be recorded. Messages with a level equal to or higher than the configured
logLevel will be captured.
- Default:
info
- Supported Levels:
error, warn, info, http, verbose, debug, silly
-
logFilePath:
- Description: Defines the path to the main application log file. This setting supports date patterns (e.g.,
%DATE%) to automatically rotate log files daily.
- Default:
logs/aicommit2-%DATE%.log (relative to the application’s state directory, typically ~/.local/state/aicommit2/logs on Linux or ~/Library/Application Support/aicommit2/logs on macOS).
-
exceptionLogFilePath:
- Description: Specifies the path to a dedicated log file for recording exceptions. Similar to
logFilePath, it supports date patterns for daily rotation.
- Default:
logs/exceptions-%DATE%.log (relative to the application’s state directory, typically ~/.local/state/aicommit2/logs on Linux or ~/Library/Application Support/aicommit2/logs on macOS).
2. AI Request/Response Logging
This system is specifically designed to log the prompts and responses exchanged with AI models for review and commit generation. These logs are stored in the application’s dedicated logs directory.
- Log Location: These logs are stored in the same base directory as the application logs, which is determined by the system’s state directory (e.g.,
~/.local/state/aicommit2/logs on Linux or ~/Library/Application Support/aicommit2/logs on macOS).
- File Naming: Each AI log file is uniquely named using a combination of the date (
YYYY-MM-DD_HH-MM-SS) and a hash of the git diff content, ensuring easy identification and chronological order.
Enable/Disable Logging
The logging setting controls whether log files are generated. It can be configured both globally and for individual AI services:
- Global
logging setting: When set in the general configuration, it controls the overall application logging (handled by Winston) and acts as a default for AI request/response logging.
- Service-specific
logging setting: You can override the global logging setting for a particular AI service. If logging is set to false for a specific service, AI request/response logs will not be generated for that service, regardless of the global setting.
Log Management
aicommit2 generates detailed logs for debugging and tracking AI requests. You can manage these log files using the built-in log commands:
View Log Files
# List all log files with details
aicommit2 log list
# Show logs directory path
aicommit2 log path
Open Log Directory
# Open logs directory in your file manager
aicommit2 log open
Clean Up Logs
# Remove all log files
aicommit2 log removeAll
- Location: Logs are stored in your system’s state directory (usually
~/.local/state/aicommit2/logs on Linux/macOS)
- Content: Each log file contains the git diff, system prompt, AI response, and metadata
- Naming: Files are named with timestamp and hash for easy identification
- Size: File sizes are displayed in human-readable format (B, KB, MB, GB)
Custom Prompt Template
aicommit2 supports custom prompt templates through the systemPromptPath option. This feature allows you to define your own prompt structure, giving you more control over the commit message generation process.
Using the systemPromptPath Option
To use a custom prompt template, specify the path to your template file when running the tool:
aicommit2 config set systemPromptPath="/path/to/user/prompt.txt"
aicommit2 config set OPENAI.systemPromptPath="/path/to/another-prompt.txt"
For the above command, OpenAI uses the prompt in the another-prompt.txt file, and the rest of the model uses prompt.txt.
NOTE: For the systemPromptPath option, set the template path, not the template content
Your custom template can include placeholders for various commit options.
Use curly braces {} to denote these placeholders for options. The following placeholders are supported:
{locale}: The language for the commit message (default: en){maxLength}: The maximum length for the commit message (default: 50){type}: The type of the commit message (conventional or gitmoji){generate}: The number of commit messages to generate (default: 1)
Example Template
Here’s an example of how your custom template might look:
Generate a {type} commit message in {locale}.
The message should not exceed {maxLength} characters.
Please provide {generate} messages.
Remember to follow these guidelines:
1. Use the imperative mood
2. Be concise and clear
3. Explain the 'why' behind the change
Appended Text
Please note that the following text will ALWAYS be appended to the end of your custom prompt:
Lastly, Provide your response as a JSON array containing exactly {generate} object, each with the following keys:
- "subject": The main commit message using the {type} style. It should be a concise summary of the changes.
- "body": An optional detailed explanation of the changes. If not needed, use an empty string.
- "footer": An optional footer for metadata like BREAKING CHANGES. If not needed, use an empty string.
The array must always contain {generate} element, no more and no less.
Example response format:
[
{
"subject": "fix: fix bug in user authentication process",
"body": "- Update login function to handle edge cases\n- Add additional error logging for debugging",
"footer": ""
}
]
Ensure you generate exactly {generate} commit message, even if it requires creating slightly varied versions for similar changes.
The response should be valid JSON that can be parsed without errors.
This ensures that the output is consistently formatted as a JSON array, regardless of the custom template used.
Code Review
aicommit2 includes an AI-powered code review feature that analyzes your staged changes before generating commit messages. When enabled, it provides structured feedback with severity levels and actionable suggestions.
Enable Code Review
# Enable globally
aicommit2 config set codeReview=true
# Or enable for specific providers only
aicommit2 config set OPENAI.codeReview=true
aicommit2 config set ANTHROPIC.codeReview=true
How It Works
When codeReview is enabled, the commit flow becomes:
- Stage changes (
git add)
- Run aicommit2 — code review runs automatically before commit message generation
- Review results — AI analyzes the diff and returns structured feedback
- Confirm or abort — choose to continue with the commit or fix issues first
- Generate commit messages — proceeds as normal after confirmation
Structured Review Output
Reviews are organized by severity and category:
- Severity levels:
critical, warning, suggestion, praise
- Categories:
bug, security, performance, style, maintainability, other
Each review item includes a title, description, file reference, and concrete suggestion for improvement. When critical issues are found, the confirmation prompt defaults to “No” to encourage fixing before committing.
Custom Review Prompt
You can customize the code review prompt using a template file:
aicommit2 config set codeReviewPromptPath="/path/to/review-prompt.txt"
aicommit2 config set OPENAI.codeReviewPromptPath="/path/to/another-prompt.txt"
The template supports the same {locale}, {type}, {generate}, {maxLength} placeholders as the commit prompt.
NOTE: When using a custom review prompt, the response format is plain text (not structured JSON). The structured severity/category output is only available with the default prompt.
WARNING: Code review runs in addition to commit message generation, which means API token usage roughly doubles per commit. If multiple providers have codeReview enabled, each provider performs its own review. Monitor your token usage carefully, especially with large diffs.
Watch Commit Mode
Watch Commit mode allows you to monitor Git commits in real-time and automatically perform AI code reviews using the --watch-commit flag.
aicommit2 --watch-commit
This feature only works within Git repository directories and automatically triggers whenever a commit event occurs. When a new commit is detected, it automatically:
- Analyzes commit changes
- Performs AI code review
- Displays results in real-time
For detailed configuration of the code review feature, please refer to the codeReview section. The settings in that section are shared with this feature.
⚠️ CAUTION
- The Watch Commit feature is currently experimental
- This feature performs AI analysis for each commit, which consumes a significant number of API tokens
- API costs can increase substantially if there are many commits
- It is recommended to carefully monitor your token usage when using this feature
- To use this feature, you must enable watch mode for at least one AI model:
aicommit2 config set [MODEL].watchMode="true"
Upgrading
Check the installed version with:
aicommit2 --version
aicommit2 doctor also compares the installed version with the npm registry and prints the upgrade command for your install method. If it’s not the latest version, run:
# Via Homebrew
brew upgrade aicommit2
# Via npm
npm update -g aicommit2
Disclaimer and Risks
This project uses functionalities from external APIs but is not officially affiliated with or endorsed by their providers. Users are responsible for complying with API terms, rate limits, and policies.
Contributing
For bug fixes or feature implementations, please check the Contribution Guide.
Contributors ✨
Thanks goes to these wonderful people (emoji key):
If this project has been helpful, please consider giving it a Star ⭐️!
Maintainer: @tak-bro
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)
评论