Python AI commit tools

A family of self-healing scripts that turn git diff --cached into a clean, conventional commit message. Five backends — Anthropic Claude, Google Gemini, OpenAI, Ollama (local), plus a smart wrapper that picks the cheapest available — share one CLI surface so flags work the same everywhere.

For a side-by-side comparison of providers, flags, costs, and setup, see the bundled comparison guide:

AI commit comparison guide (full text)

AI Commit Tools Comparison

This folder contains two AI-powered commit message generators that use different Large Language Models.

Available Tools

1. aic.py - Google Gemini (Recommended for free tier)

• Model: Uses Google Gemini models (default: gemini-2.0-flash)
• API Key: Requires GOOGLE_API_KEY or GEMINI_API_KEY environment variable
• Git Alias: git aic
• Pros:
• Generous free tier
• Fast response times
• Good for high-volume usage
• Setup: Get your API key from Google AI Studio

2. aico.py - OpenAI (Recommended for best quality)

• Model: Uses OpenAI models (default: gpt-4o)
• API Key: Requires OPENAI_API_KEY environment variable
• Git Alias: git aico
• Pros:
• State-of-the-art quality
• Excellent instruction following
• Access to latest GPT models
• Setup: Get your API key from OpenAI Platform

Quick Start

Setup Environment Variables

For Gemini (aic.py): ```powershell

PowerShell

$env:GOOGLE_API_KEY="your-google-api-key"

Or permanently in System Environment Variables

setx GOOGLE_API_KEY "your-google-api-key" ```

For OpenAI (aico.py): ```powershell

PowerShell

$env:OPENAI_API_KEY="your-openai-api-key"

Or permanently in System Environment Variables

setx OPENAI_API_KEY "your-openai-api-key" ```

Usage Examples

Both tools support the same command-line flags and workflows:

```bash

Basic usage (files already staged)

git aic # Using Gemini git aico # Using OpenAI

Interactive staging with fzf

git aic -i # Using Gemini git aico -i # Using OpenAI

Stage all and commit

git aic -a # Using Gemini git aico -a # Using OpenAI

Review before committing

git aic -r # Using Gemini git aico -r # Using OpenAI

Complete workflow: stage all, review, commit, push

git aic -arp # Using Gemini git aico -arp # Using OpenAI

Select custom model interactively

git aic -m # Select from Gemini models git aico -m # Select from OpenAI models

Dry run (see message without committing)

git aic -d # Using Gemini git aico -d # Using OpenAI ```

Command Flags

Both tools support identical flags:

Flag	Description
-a, --add-all	Stage all changes before committing
-d, --dry-run	Show generated message without committing
-f, --fill-placeholders	Use extended prompt with placeholders
-i, --interactive-add	Interactive file staging with fzf
-m, --model	Select custom model interactively
-p, --push	Push after successful commit
-r, --review	Review and approve message before commit
-v, --debug	Enable verbose logging
-w, --watermark	Add "Generated by [AI]" signature

Which One Should I Use?

Use git aic (Gemini) if:

• You're on a budget or free tier
• You need fast response times
• You make frequent commits
• You want to avoid rate limits

Use git aico (OpenAI) if:

• You prioritize commit message quality
• You have OpenAI credits available
• You want access to the latest GPT models
• You need more precise instruction following

Installation

1. Ensure Python is installed
2. Run gitinit.cmd to set up aliases
3. Both tools auto-install dependencies on first run via dependency_manager.py

Future Plans

A unified script with runtime model selection is planned: ```bash

Future syntax (not yet implemented)

git aic --provider gemini # Use Gemini git aic --provider openai # Use OpenAI ```

Dependencies

• aic.py: requests (for Gemini REST API)
• aico.py: openai (official OpenAI Python SDK)

Both use the local dependency_manager.py for automatic dependency installation.

Troubleshooting

Rate Limit Errors

Gemini (429 error): - Check quota at Google AI Studio - Wait a few minutes between requests - Consider spacing out commits

OpenAI (429 error): - Check usage at OpenAI Dashboard - Add credits to your account - Upgrade to a higher tier plan

API Key Not Found

Make sure your environment variable is set correctly: ```powershell

Check if variable is set

echo $env:GOOGLE_API_KEY echo $env:OPENAI_API_KEY ```

Model Not Available

Use the -m flag to see available models for your API key: bash git aic -m # List Gemini models git aico -m # List OpenAI models

Cost Comparison

Provider	Model	Input (per 1M tokens)	Output (per 1M tokens)	Free Tier
Google Gemini	gemini-2.0-flash	Free (up to limit)	Free (up to limit)	Yes, generous
OpenAI	gpt-4o	$2.50	$10.00	$5 credit for new users
OpenAI	gpt-4	$30.00	$60.00	N/A

Prices as of February 2026, check official pricing for updates

License

These tools are part of the power-user-scripts repository.

---

The smart wrapper

aic.py

aic

Smart AI commit wrapper — auto-selects the cheapest available provider.

Priority order (most preferred → least preferred): 0. Ollama (local) (auto-detected at localhost:11434) → aicl.py 1. Anthropic Claude (ANTHROPIC_API_KEY) → aica.py 2. Google Gemini (GOOGLE_API_KEY / GEMINI_API_KEY) → aicg.py 3. OpenAI (OPENAI_API_KEY) → aico.py

This is a thin wrapper: it detects which provider is available, prints one line showing the chosen provider, then hands full control to the backend script. All CLI flags (-a, -d, -r, -i, -p, -f, -m, -v, -w, FILES...) are forwarded unchanged so every feature of the underlying script is available.

Override flags (consumed by this wrapper, NOT forwarded to the backend): -c, --cloud Skip Ollama even when it is running; use best available cloud provider instead (Anthropic → Gemini → OpenAI).

---

Provider backends

aica.py — Anthropic Claude

aica

AI-powered Git commit message generator using Anthropic Claude. Generates conventional commit messages using Anthropic's models.

aicg.py — Google Gemini

aicg

AI-powered Git commit message generator using Google Gemini. Generates conventional commit messages using Google's Gemini models.

aico.py — OpenAI

aico

AI-powered Git commit message generator using OpenAI. Generates conventional commit messages using OpenAI's models.

aicl.py — Ollama (local)

aicl

AI-powered Git commit message generator using Ollama (local). Generates conventional commit messages using locally-running Ollama models. No API key required — uses the Ollama REST API at localhost:11434.

Smart RAM management

• num_ctx is capped (default 8192) to prevent models inflating to 30+ GB RAM
• PREFERRED_MODELS ordered small→large so lighter models are tried first
• Automatic fallback: timeout/crash/OOM → retries with next smaller model

---

Companion utilities

chat.py

chat

aipr.py

aipr

dependency_manager.py

dependency_manager

🛡️ Dependency Manager (Self-Healing Environment Engine)

A drop-in module to ensure Python scripts automatically install their own dependencies before execution. It uses a "Hierarchy of Trust" security model to prevent dependency confusion attacks.

Usage

import dependency_manager

Method 1: The Smart List (Recommended)

Automatically resolves pip names using the Internal Golden Map.

dependency_manager.require(["requests", "cv2", "yaml"])

Method 2: The Explicit Override (For private packages or version pinning)

dependency_manager.require({ "my_module": "my-private-package>=1.0.0", "legacy_lib": "legacy-pkg==2.4.1" })

Debug Mode

Run your main script with '--debug' to see verbose installation logs. e.g., python my_script.py --debug