Overview

This page covers what ai-commit is, what it does, its supported AI backends, key features, and the top-level architecture of the codebase. For installation steps, see Getting Started. For detailed CLI usage, see the User Guide. For internal implementation details, see Architecture Deep Dive.

---

What is ai-commit?

ai-commit is a PHP command-line tool that reads the staged git diff in a repository and calls an AI service to produce a Conventional Commits-formatted commit message. The user then confirms or rejects the message before it is committed.

One-line description (from composer.json): "Automagically generate conventional git commit message with AI."

The tool is distributed as:

• A self-contained PHAR binary (builds/ai-commit), downloadable directly or via self-update.
• A Composer package (guanguans/ai-commit).

Runtime requirement: PHP >= 8.2 with the ext-curl and ext-mbstring extensions.

License: MIT

Framework: Laravel Zero — a micro-framework for console applications built on Laravel.

Sources: composer.json1-68 README.md1-45

---

Supported AI Backends

ai-commit calls these backends through interchangeable "generators". Each has a corresponding driver key used in configuration and the --generator flag.

Driver Key	Backend	Type
openai_chat	OpenAI Chat Completions API	API (HTTP)
openai	OpenAI Completions API (legacy)	API (HTTP)
moonshot	Moonshot (Kimi) API	API (HTTP)
ernie_bot	Baidu ERNIE-Bot	API (HTTP)
ernie_bot_turbo	Baidu ERNIE-Bot Turbo	API (HTTP)
bito_cli	Bito CLI (bito binary)	CLI subprocess
github_copilot_cli	GitHub Copilot CLI (gh copilot)	CLI subprocess
github_models_cli	GitHub Models CLI (gh models)	CLI subprocess

The default generator is openai_chat unless overridden in configuration.

Sources: README.md21-31 composer.json7-37

---

Key Features

Feature	Description
AI-generated commit messages	Sends git diff --staged output to a selected AI generator and returns a structured JSON message
Conventional commit type selection	Interactive prompt lets the user select or auto-generate the commit type (feat, fix, docs, etc.)
Confirmation loop	Displays the generated message in a table and asks for confirmation before committing
--dry-run mode	Generates and displays the message without executing git commit
--diff option	Accepts explicit diff content instead of reading from git
Three-layer configuration	Defaults → global (~/.ai-commit/.ai-commit.json) → local (.ai-commit.json)
config sub-command	set, get, unset, reset, list, edit operations on both global and local config
self-update	Updates the PHAR binary from GitHub Releases
Retry logic	Configurable retry count and sleep between retries for API failures

Sources: README.md53-239

---

Top-Level Architecture

Component Relationships

Diagram: Top-level component map

Sources: README.md53-75 composer.json58-68

---

Commit Workflow Overview

Diagram: CommitCommand data flow

Sources: README.md76-130

---

Generator Class Hierarchy

Diagram: Generator system — class and interface relationships

Sources: README.md21-31 composer.json58-68

---

Configuration System

Diagram: Configuration layer merge order

The ConfigManager class (in app/Support/ConfigManager.php) extends the Illuminate Config Repository and performs a three-way merge. The config command reads and writes to either the global or local file depending on the --global flag.

Sources: README.md166-182

---

Project Structure Summary

Path	Purpose
app/Commands/	CommitCommand, ConfigCommand, ThanksCommand
app/Generators/	GeneratorManager, AbstractGenerator, all driver classes
app/Clients/	HTTP client classes for API-based generators
app/Support/	ConfigManager, helper functions
app/Contracts/	GeneratorContract and other interfaces
config/ai-commit.php	Default configuration (generators, prompts, commit types)
config/commands.php	Command registration list
builds/ai-commit	Compiled PHAR binary
tests/	Pest test suite (Feature + Unit)
.github/workflows/	CI/CD workflows (tests, PHPStan, PHP-CS-Fixer, release)

Sources: composer.json133-148 README.md240-266

---

Further Reading

Topic	Page
Installation and first-run	Getting Started
End-to-end commit workflow	Commit Command Workflow
All CLI flags and options	Command Options and Flags
Configuration management	Configuration Management
All generators in detail	AI Generators Overview
Internal architecture	Architecture Deep Dive
Generator implementation	Generator System
Adding a new generator	Adding New Generators
Configuration file format	Configuration Reference