Ai Commit Laravel Package

Getting Started

Install globally so the binary is available in every repo:

composer global require guanguans/ai-commit
# ensure ~/.composer/vendor/bin (or ~/.config/composer/vendor/bin) is on PATH

Create a config file with your provider credentials:

ai-commit config
# or drop a JSON file at ~/.config/ai-commit/config.json (Linux/macOS)
#   %APPDATA%\ai-commit\config.json (Windows)

A minimal config.json looks like:

{
  "openai": {
    "api_key": "sk-...",
    "model": "gpt-4o-mini"
  }
}

First use case: stage some files, then run ai-commit from the repo root. It reads git diff --cached, sends the diff to the configured generator, prints a few conventional-commit candidates, and lets you pick one, edit it, or commit directly. Start by running it with --dry-run (or just declining the commit prompt) so you can eyeball message quality before letting it touch your history.

Look first at:

1. The config.json schema for your chosen provider (OpenAI, Anthropic, Gemini, Ollama, DeepSeek, etc. — the generator block is what you'll tweak most).
2. The default prompt template shipped with the package; it's the thing you'll customize when messages come out wrong.
3. ai-commit --help — flags like --commit, --edit, --no-verify, --dry-run, --prompt, --generator are the daily levers.

Implementation Patterns

Per-repo overrides. Drop an .ai-commit.json at the project root to pin a generator, model, or prompt for that repo only. Useful when a monorepo needs different commit conventions than your personal default, or when one project uses a local Ollama instance for privacy.

Generator selection. Set a default in the global config, then switch ad-hoc with --generator=anthropic for a single run. Pattern: keep OpenAI as the default for speed, but define an anthropic or ollama block and flip to it for sensitive diffs you don't want leaving the machine.

Prompt customization. The real win is replacing the stock prompt with one tuned to your team's style — scope prefixes, ticket ID conventions, language (the package supports zh/en out of the box). Keep the prompt file in dotfiles or commit it as part of the .ai-commit.json prompt field.

Interactive vs. scripted flow. Two modes:

• Interactive: ai-commit → review candidates → edit → commit. Best for normal development.
• Direct: ai-commit --commit --no-verify for a one-shot commit when you trust the output. Wire this into a shell alias like aik='ai-commit --commit --no-verify' for throwaway branches — but always keep the review step for anything headed to main.

Editor integration. Because ai-commit shells out to $EDITOR when you hit "edit," it composes well with a git hook that pre-populates COMMIT_EDITMSG, or with git commit --amend workflows where you re-run ai-commit --edit to regenerate a message after adding files.

Diff scoping. Stage selectively before running — the tool only sees --cached. A useful pattern is git add -p then ai-commit, which gives the model a tighter, more coherent diff and reliably better messages than dumping a huge unstaged changeset.

CI / scripting. For release automation, call ai-commit --dry-run --commit 2>/dev/null in a pipeline and capture the last candidate from stdout. It's not designed as a library, so treat it as a CLI shim, not an SDK.

Gotchas and Tips

• Config is not project-committed by default. Anything with an API key in .ai-commit.json should be gitignored; keep the key in the global config or an env var (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.) and reference the provider block only.
• Large diffs blow tokens and quality. The prompt sends the full staged diff. If you're committing a formatted codebase, stage in batches. There's no built-in diff truncation warning — you'll just get vaguer messages or a provider error.
• Provider names are string keys, not case-insensitive. A typo in --generator=openai vs openai (or a missing config block) fails silently or falls back to the first defined generator; check with --dry-run and --verbose first.
• --no-verify is tempting but skips your commit hooks. Don't bake it into a git commit alias; keep it manual. Combined with --commit it's the most dangerous flag combo in the package.
• Config path on macOS/Windows differs. If the binary "ignores" your config, you're likely editing ~/.ai-commit.json while it reads ~/Library/Application Support/ai-commit/config.json. Run ai-commit config --help or inspect the error message to confirm the path.
• ai-commit config is interactive and can overwrite your file — back it up if you've hand-tuned a prompt template. There's no --merge mode.
• Model quality dominates everything. gpt-4o-mini is fast but flattens nuance; for a repo with a strong conventional-commit convention, pin gpt-4o or claude-3-5-sonnet in the config rather than relying on the cheap default.
• Network failures surface as opaque git errors because the tool wraps git commit. Run with the message printed first (decline the commit) to isolate whether the failure was the AI call or git.
• Extension point is the prompt, not plugins. There's no hook system for post-processing messages — if you need a ticket-ID prefix injected, do it in the prompt template or wrap the binary in a shell function.
• Language toggle. If messages come out in the wrong language, that's the language field in config (or the prompt template's instructions), not a bug — the package is bilingual and picks based on this setting.
• Version pinning. 394 stars and a May 2025 release means active but not battle-hardened; pin a version in your global composer.json ("guanguans/ai-commit": "~1.x") so a breaking prompt or config change doesn't silently alter how your commits read.