ai-commit

Generate clean git commit messages from your staged diff using Codex or OpenCode.

ai-commit is a small Python CLI that works in any git repository. It stages changes by default, asks an AI provider for a Conventional Commit message, shows a preview, and then asks before creating the commit.

Default model:

codex/gpt-5.4-mini

Preview

Files changed:
  M src/foo.ts
  A tests/foo.test.ts

Suggested:
  feat(cli): add provider selection

Install

For local development, use a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

If you want to install the CLI from this local checkout as an app, use pipx:

pipx install -e .

After publishing to PyPI, the intended public install path is:

pipx install ai-commit

Usage

Create a commit from all current changes:

ai-commit

Use a model shortcut:

ai-commit gpt
ai-commit kimi
ai-commit qwen
ai-commit glm
ai-commit minimax

Use only files that are already staged:

ai-commit --staged-only

Show the preview without creating a commit:

ai-commit --dry-run

Hide progress messages:

ai-commit --quiet

Force a provider for one run:

ai-commit --provider codex
ai-commit --provider opencode

Force a model for one run:

ai-commit --provider opencode --model opencode-go/kimi-k2.5

Skip the confirmation prompt:

ai-commit --yes

Configuration

Optional global config file:

~/.config/ai-commit/config.json

Example:

{
  "provider": "codex",
  "codex_model": "gpt-5.4-mini",
  "opencode_model": "opencode-go/kimi-k2.5",
  "confirm": true,
  "staged_only": false,
  "max_diff_chars": 120000
}

By default, ai-commit runs git add -A before reading the staged diff. Set "staged_only": true or pass --staged-only to commit only changes you staged manually.

Providers

For Codex, the codex command must be available in PATH.

For OpenCode, the opencode command must be available in PATH.

For OpenCode Go, use model ids like:

ai-commit kimi    -> opencode-go/kimi-k2.5
ai-commit qwen    -> opencode-go/qwen3.6-plus
ai-commit glm     -> opencode-go/glm-5
ai-commit minimax -> opencode-go/minimax-m2.5

Equivalent model ids:

opencode-go/kimi-k2.5
opencode-go/glm-5
opencode-go/minimax-m2.5
opencode-go/qwen3.6-plus

VS Code or Windsurf

You can call the CLI from a global user task:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "AI Commit",
      "type": "shell",
      "command": "ai-commit",
      "options": {
        "cwd": "${workspaceFolder}"
      },
      "presentation": {
        "reveal": "always",
        "panel": "dedicated",
        "focus": true
      },
      "problemMatcher": []
    }
  ]
}

Development

Run tests:

python -m pip install -e .
python -m unittest discover -s tests

Without installing the package:

PYTHONPATH=src python -m unittest discover -s tests

Check the CLI:

ai-commit --version