Getting Started

This page covers the minimum steps required to install ai-commit, configure an AI backend, and run your first AI-generated commit. It targets new users who want to be operational quickly.

For a detailed explanation of every CLI flag and option, see Command Options and Flags. For managing configuration files after initial setup, see Configuration Management. For a deeper look at how the generator system works internally, see Generator System Architecture.

---

Requirements

Requirement	Version
PHP	>= 8.2
Git	Any recent version

The PHAR build (builds/ai-commit) ships with all PHP dependencies bundled via Humbug Box so no Composer installation is needed if you use that method.

Sources: README.md33-35

---

Installation

There are two supported installation methods. Choose one.

Method 1 — Download the PHAR

The pre-built PHAR is committed to the repository at builds/ai-commit Download it and make it executable:

After this, you can run the tool as ./ai-commit from any directory. The file is a self-contained PHP archive generated by Box (builds/ai-commit1-16).

Method 2 — Install via Composer

When installed globally, the ai-commit binary is available system-wide via Composer's global bin path.

Sources: README.md38-51 builds/ai-commit1-16

---

How the Tool Works (Overview)

Before configuring, it is useful to understand the data flow from invocation to git commit.

ai-commit entry point and execution flow:

Sources: ai-commit1-65 README.md53-133

---

Choosing and Configuring a Generator

ai-commit supports multiple AI backends, called generators. Each generator has its own configuration block under generators.* in the config.

Supported generators and their required configuration:

Generator key	Type	Required config
openai_chat	API	generators.openai_chat.api_key
openai	API	generators.openai.api_key
moonshot	API	generators.moonshot.api_key
ernie_bot	API	generators.ernie_bot.api_key
ernie_bot_turbo	API	generators.ernie_bot_turbo.api_key
bito_cli	CLI binary	generators.bito_cli.binary (optional)
github_copilot_cli	CLI binary	generators.github_copilot_cli.binary (optional)
github_models_cli	CLI binary	generators.github_models_cli.binary (optional)

The default generator is openai_chat. You can override the default using the config set generator command.

Sources: README.md21-31 README.md60-73

---

Initial Configuration

Configuration is stored in JSON files and managed through the config sub-command. The --global flag writes to ~/.ai-commit/.ai-commit.json, which applies to all repositories on your machine.

Setting an API key (example: OpenAI Chat):

Setting the default generator:

Quick setup for all generators (set only what you use):

Configuration key path to class mapping:

Sources: README.md60-73 README-zh_CN.md60-73

---

First Run

Once at least one generator is configured, stage your files and run the commit command.

Step 1: Stage your changes

Step 2: Run ai-commit

This uses the default generator (openai_chat unless changed). To use a specific generator for a single run:

What happens next

The tool walks through three numbered steps in the terminal:

1. Generating commit message: generating...
 [commit type selection prompt appears]
 [AI generates JSON with subject + body]
1. Generating commit message: ✔

2. Confirming commit message: confirming...
 [table showing subject and body]
 Do you want to commit this message? (yes/no) [yes]:
2. Confirming commit message: ✔

3. Committing message: committing...
3. Committing message: ✔

 [OK] Successfully generated and committed message.

The ai-commit.tape file (ai-commit.tape60-70) is the VHS script used to record the demo GIF at resources/docs/ai-commit-vhs.gif.

Sources: README.md55-133 ai-commit.tape60-70

---

Commit Type Selection

Before the AI call, the tool prompts you to choose a commit type. Selecting auto lets the AI decide; selecting a specific type (e.g., feat, fix, chore) constrains the generated message.

 Please choose commit type [Automatically generate commit type]:
 [auto ] Automatically generate commit type
 [feat ] A new feature
 [fix ] A bug fix
 [docs ] Documentation only changes
 [style ] Changes that do not affect the meaning of the code
 [refactor] A code change that neither fixes a bug nor adds a feature
 [perf ] A code change that improves performance
 [test ] Adding missing tests or correcting existing tests
 [build ] Changes that affect the build system or external dependencies
 [ci ] Changes to our CI configuration files and scripts
 [chore ] Other changes that don't modify src or test files
 [revert ] Reverts a previous commit

These types are defined in config/ai-commit.php and can be customized. See Commit Types Configuration for details.

Sources: README.md79-92

---

Common Workflows

Generate without committing (dry run):

Skip the editor and hook steps:

Use a specific generator for one run:

View or edit your global config directly:

Sources: README.md166-182 README.md207-237

---

Self-Update

The PHAR build supports in-place self-update:

Output example:

Checking for a new version...
=============================

 [OK] Updated from version 1.2.4 to v1.2.5.

Sources: README.md184-199

---

Available Commands Summary

USAGE: ai-commit <command> [options] [arguments]

 commit Automagically generate conventional commit message with AI.
 completion Dump the shell completion script
 config Manage config options.
 self-update Allows to self-update a build application
 thanks Thanks for using this tool.

For a full reference of commit options (including --diff, --prompt, --retry-times, etc.) see Command Options and Flags.

Sources: README.md140-162