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.
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:
builds/ai-commit), downloadable directly or via self-update.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
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
| 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
Diagram: Top-level component map
Sources: README.md53-75 composer.json58-68
Diagram: CommitCommand data flow
Sources: README.md76-130
Diagram: Generator system — class and interface relationships
Sources: README.md21-31 composer.json58-68
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
| 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
| 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 |
Refresh this wiki
This wiki was recently refreshed. Please wait 5 days to refresh again.