Git AIC: AI-Powered Conventional Commits

Git AIC is a TypeScript CLI for two related workflows inside a Git repository:

• generating AI-assisted conventional commit messages from staged changes
• generating AI-explained markdown diff reports from selected working-tree changes

It is built for local Git usage with interactive file selection, Gemini-based summarization, and a low-friction terminal UX.

What It Does

Commit flow

git aic

• inspects the repository for changed files
• auto-stages deleted files for commit workflows
• lets you choose which files should be part of the commit when there are multiple changed files
• stages newly selected files and unstages deselected staged files
• sends the staged diff to Gemini
• generates a Conventional Commits style message
• commits with that message

git aic --push / git aic -p

• runs the same commit flow
• pushes after a successful commit

Diff report flow

git aic --diff / git aic -d

• inspects the repository for changed files
• lets you choose which files should be included in the report when there are multiple changed files
• does not stage or unstage files for the diff workflow
• reads the selected changes directly from the working tree
• generates a markdown report in git-diffs/
• explains each selected file diff with AI
• includes current repo metadata such as branch and base commit hash

Key Behaviors

• Conventional commit generation: Commit messages are guided by strict prompt rules.
• Single logical change stays one line: If multiple files all belong to one logical change, the generated commit message stays a one-line summary.
• Unrelated changes may become a list: If the changes are clearly unrelated, the generated commit message may use a summary line plus bullet points.
• Interactive file selection: Multi-file changes open a selector so the user can choose the exact file set to commit, push, or document.
• AI diff reports: Diff reports explain the selected changes before showing the raw patch.
• Structured diff naming: Report filenames use a concise type-topic.md format such as feat-auth-flow.md.
• Organized output: Reports are written to git-diffs/ in the current working directory.
• Git ignore support: On the first diff report run that creates git-diffs/, the tool adds git-diffs/ to the current directory’s .gitignore if it is not already ignored.
• Visible loading states: Uses cli-loaders with the arrows_3 loader and step-specific status messages.
• Retry-safe AI requests: Retries temporary Gemini rate limits and transient failures, then falls back cleanly if needed.

Diff Report Contents

Each generated markdown report includes:

• report title
• metadata section
• generated timestamp
• current branch
• short base commit hash
• full base commit hash
• selected file list
• one section per file
• AI explanation above the raw diff block

Installation

1. Global Installation (Standard)

The easiest way to use Git AIC is to install it globally via npm or bun:

npm install -g @amnesia2k/git-aic
# or
bun install -g @amnesia2k/git-aic

Once installed, you can skip the manual setup and use the built-in configuration commands:

• git-aic set-key your_gemini_api_key_here
• git-aic alias

2. Local Development (Clone)

For developers or users who want to run the tool from the source code:

1. Clone the repository:

git clone https://github.com/amnesia2k/git-aic.git
cd git-aic

2. Install dependencies:

bun install

3. (Optional) Link the package locally:

npm link

Configuration & API Key

Git AIC requires a Google Gemini API key.

A. Persistent Configuration (Recommended)

You can securely store your API key in your user profile:

git-aic set-key your_gemini_api_key_here

To see your current configuration:

git-aic show

B. Environment Variables (Manual)

Alternatively, you can set the GEMINI_COMMIT_MESSAGE_API_KEY variable.

Windows PowerShell:

setx GEMINI_COMMIT_MESSAGE_API_KEY "your_gemini_api_key_here"

MacOS & Linux:

export GEMINI_COMMIT_MESSAGE_API_KEY=your_gemini_api_key_here

Restart the terminal after setting the variable.

Usage

1. The "git aic" Alias

To use the tool as a native Git subcommand (git aic), you need to set up a Git alias.

Option A: Automatic Setup (Global NPM)

If you installed via NPM, run:

git-aic alias

Option B: Manual Setup (Local Clone)

If you are running from a local clone, point the alias to your entry point:

Windows PowerShell:

git config --global alias.aic '!npx tsx "C:/Users/YourName/path/to/git-aic/bin/cli.ts"'

macOS / Linux:

git config --global alias.aic '!npx tsx "/Users/YourName/path/to/git-aic/bin/cli.ts"'

2. Commands

Generate and create a commit:

git aic

Generate, commit, and push:

git aic --push

Generate a markdown diff report:

git aic --diff

Show current configuration:

git aic show

Display help:

git aic help

Tip

Use git aic help or git aic -h to see the help menu. Git reserves --help for its own internal documentation search, which causes raw --help to fail on custom aliases.

Also supported:

git aic -d : This is a shortcut for `git aic --diff`
git aic -p : This is a shortcut for `git aic --push`

Important Workflow Notes

Commit mode stages files

Commit workflows are based on the staged diff.

When you select files for commit mode:

• unselected staged files are unstaged
• selected unstaged files are staged
• the final commit message is generated from the resulting staged diff

Diff mode does not stage files

Diff report workflows are based on the selected changes directly.

When you select files for -d / --diff:

• the tool does not stage files
• the tool does not unstage files
• the tool reads the selected diffs and generates the markdown report from them

This keeps the report flow non-destructive and avoids changing index state unnecessarily.

Example Output Location

Example generated report paths:

• git-diffs/feat-auth-flow.md
• git-diffs/fix-config-loading.md
• git-diffs/refactor-cli-loader.md

If a filename already exists, numeric suffixes are used:

• feat-auth-flow.md
• feat-auth-flow-1.md
• feat-auth-flow-2.md

Technologies Used

Technology	Description
	Primary language for robust and scalable code.
	JavaScript runtime used to execute the CLI tool.
	Fast all-in-one JavaScript runtime.
	Large Language Model for intelligent commit message generation.
	Promise-based HTTP client for API requests.
	Facilitates Git operations programmatically.
	Interactive command-line interface prompts.
	Provides animated terminal loaders for visible CLI progress.
	Terminal string styling for enhanced readability.
	Framework for building robust command-line interfaces.
	Runs the TypeScript CLI entrypoint directly during local usage.
	Supports direct TypeScript execution in the project scripts.

License

This project is licensed under the MIT License. See the file for details.

Author Info

Developed by a passionate software engineer.

• Olatilewa Olatoye
• LinkedIn: [Olatilewa Olatoye]
• X (formerly Twitter): [@olathedev_]

Badges