PHPackages                             tharlesamaro/laravel-git-ai - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. tharlesamaro/laravel-git-ai

ActiveLibrary[Utility & Helpers](/categories/utility)

tharlesamaro/laravel-git-ai
===========================

AI-powered Git workflow automation for Laravel: smart commit messages, changelog generation, and commit validation using Conventional Commits.

v0.3.0(3mo ago)02MITPHPPHP ^8.4

Since Feb 11Pushed 3mo agoCompare

[ Source](https://github.com/tharlesamaro/laravel-git-ai)[ Packagist](https://packagist.org/packages/tharlesamaro/laravel-git-ai)[ RSS](/packages/tharlesamaro-laravel-git-ai/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (5)Versions (4)Used By (0)

Laravel Git AI
==============

[](#laravel-git-ai)

[![Latest Version on Packagist](https://camo.githubusercontent.com/050f4d0bde894d4703cb5406df8d79fe125037f25f805d840500edcd7dc0f555/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f746861726c6573616d61726f2f6c61726176656c2d6769742d61692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tharlesamaro/laravel-git-ai)[![Total Downloads](https://camo.githubusercontent.com/8a2d00ffb331d748e878d743a89bf45fec082183fb72ee337148706822f29ac4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f746861726c6573616d61726f2f6c61726176656c2d6769742d61692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tharlesamaro/laravel-git-ai)

**English** | [Portugues](README.pt-BR.md)

AI-powered Git workflow automation for Laravel. Generate smart commit messages, changelogs, and validate commits using Conventional Commits.

Why use this package instead of Claude Code directly?
-----------------------------------------------------

[](#why-use-this-package-instead-of-claude-code-directly)

If you already use Claude Code CLI, you might wonder: "Why not just ask Claude to commit for me?" Here's what this package brings to the table:

FeatureClaude Code aloneLaravel Git AIConventional Commits formatYou have to ask every timeEnforced automatically via structured outputConsistent JSON schemaFree-form text, may varyValidated against a strict schema every timeProject-specific scopesMust remember to mention themConfigured once, enforced on every commitAllowed commit typesManual disciplineRestricted by config, AI cannot use othersMulti-language supportMust specify in every promptConfigured once, always appliedChangelog generationManual workAutomated from commit history between tagsGit hook validationNot availableOptional hook rejects non-conventional commitsTeam consistencyEach developer prompts differentlySame rules for everyone via shared configMax diff size controlNo control, may exceed contextAuto-truncated to configured limitWorks without CLI installedN/AFalls back to API providers (Anthropic/OpenAI)In short: this package turns AI-generated commits into a **repeatable, team-wide standard** instead of a one-off prompt.

Features
--------

[](#features)

- **`git:commit`** -- Generate commit messages from staged changes using AI, following Conventional Commits
- **`git:changelog`** -- Generate structured changelogs from commit history between tags
- **`git:setup`** -- Interactive configuration wizard
- **3 providers** -- Anthropic API, OpenAI API, or Claude Code CLI (no API key needed)
- **9 languages** -- English, Portuguese, Spanish, French, German, Italian, Japanese, Korean, Chinese
- **Scope enforcement** -- Restrict commits to project-specific scopes
- **Type restriction** -- Limit which Conventional Commits types are allowed
- **Commit templates** -- Built-in (`minimal`, `detailed`) and custom presets for body + footer settings
- **Body control** -- Configure whether AI always includes body, never includes it, or decides automatically
- **Footer control** -- Toggle BREAKING CHANGE footer, add custom footer lines, control Co-Authored-By trailer
- **Git hook** -- Optional `commit-msg` hook to reject non-conventional commits
- **Structured output** -- AI responses are validated against a JSON schema, never free-form text
- **Diff truncation** -- Large diffs are automatically truncated to fit AI context windows

Requirements
------------

[](#requirements)

- PHP 8.4+
- Laravel 12+
- One of the following:
    - [Laravel AI SDK](https://laravel.com/docs/12.x/ai-sdk) (`laravel/ai`) + an API key from Anthropic or OpenAI
    - **OR** [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed on your machine (uses your existing Claude subscription, e.g. Max plan -- no API key required)

Installation
------------

[](#installation)

```
composer require tharlesamaro/laravel-git-ai
```

Publish the configuration file:

```
php artisan vendor:publish --tag=git-ai-config
```

Run the interactive setup:

```
php artisan git:setup
```

Provider Setup
--------------

[](#provider-setup)

### Option 1: Anthropic API (default)

[](#option-1-anthropic-api-default)

```
GIT_AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=your-api-key
```

### Option 2: OpenAI API

[](#option-2-openai-api)

```
GIT_AI_PROVIDER=openai
OPENAI_API_KEY=your-api-key
```

### Option 3: Claude Code CLI (no API key)

[](#option-3-claude-code-cli-no-api-key)

If you have a Claude subscription (e.g. Max plan) and the Claude Code CLI installed, you can use it directly without any API key:

```
GIT_AI_PROVIDER=claude-code
```

Make sure the `claude` binary is available in your PATH. Install it from:

This option invokes the Claude Code CLI as a subprocess, passing a structured prompt and parsing the JSON response. It consumes from your existing subscription usage -- no separate API tokens needed.

Usage
-----

[](#usage)

### `git:commit` -- Generate a commit message

[](#gitcommit----generate-a-commit-message)

Stage your changes and run:

```
php artisan git:commit
```

Or stage everything automatically with the `--all` (`-a`) flag:

```
php artisan git:commit --all
```

**Available options:**

OptionShortDescription`--all``-a`Stage all changes before committing`--template=`Use a named commit template (e.g. `minimal`, `detailed`)`--no-body`Strip body from the commit message`--footer=`Add custom footer line(s) (can be used multiple times)**What happens:**

1. Reads your staged diff (truncated if it exceeds `max_diff_size`)
2. Sends it to the configured AI provider
3. Receives a structured response with `type`, `scope`, `description`, `body`, and `is_breaking_change`
4. Validates the type and scope against your config
5. Formats the message following Conventional Commits
6. Lets you choose what to do next

**Interactive menu:**

```
Staged changes:
 src/Models/User.php    | 12 ++++++---
 src/Http/AuthController.php | 8 ++++--
 2 files changed, 14 insertions(+), 6 deletions(-)

Generated commit message:
  feat(auth): add email verification on registration

What would you like to do?
  > Accept and commit
    Edit the message
    Generate a new suggestion
    Cancel

```

- **Accept and commit** -- Creates the commit with the generated message
- **Edit the message** -- Opens an editor to modify the title and body separately
- **Generate a new suggestion** -- Calls the AI again for a different message
- **Cancel** -- Aborts without committing

**Example with body and breaking change:**

```
Generated commit message:
  feat(api)!: replace REST endpoints with GraphQL

  Migrate all API endpoints from REST to GraphQL.
  This removes all /api/v1/* routes.

  BREAKING CHANGE: replace REST endpoints with GraphQL

```

### `git:changelog` -- Generate a changelog

[](#gitchangelog----generate-a-changelog)

```
php artisan git:changelog
```

**Available options:**

OptionDescriptionDefault`--from=`Starting tag or commit hashLatest tag (or first commit if no tags)`--to=`Ending tag or commit hash`HEAD``--tag=`Version tag for the changelog headerInteractive prompt`--dry-run`Preview without writing to file`false`**Examples:**

```
# Auto-detect range (latest tag to HEAD)
php artisan git:changelog

# From a specific tag to HEAD
php artisan git:changelog --from=v1.0.0

# Between two references
php artisan git:changelog --from=v1.0.0 --to=v1.1.0

# Specify the version tag upfront
php artisan git:changelog --tag=v2.0.0

# Preview without writing to file
php artisan git:changelog --dry-run

# Combine options
php artisan git:changelog --from=v1.0.0 --to=v2.0.0 --tag=v2.0.0 --dry-run
```

**What happens:**

1. Resolves the starting reference (priority: `--from` > latest tag > first commit)
2. Gets all commits between `from` and `to`
3. Parses each commit message using the Conventional Commits format
4. Groups commits by type (`feat`, `fix`, `docs`, etc.)
5. Sends the grouped commits to the AI for human-readable descriptions
6. Formats the output as Markdown with emojis (configurable)
7. Shows a preview and asks for confirmation before writing

**Output example (`CHANGELOG.md`):**

```
## [v1.2.0] - 2026-02-11

### Features

- Add email verification during user registration
- Implement password reset via SMS

### Bug Fixes

- Resolve null pointer when loading user preferences
- Fix timezone handling in scheduled notifications

### Documentation

- Update API authentication guide with OAuth2 examples
```

If `changelog.with_emojis` is enabled (default), section titles include emojis:

```
### ✨ Features
### 🐛 Bug Fixes
### 📚 Documentation
### ♻️ Code Refactoring
### ⚡ Performance Improvements
### 🧪 Tests
### 📦 Build System
### 🔧 Continuous Integration
### 🔨 Chores
### ⏪ Reverts
```

The changelog is prepended to the existing file. If `CHANGELOG.md` already exists, new content is added at the top (below the header), preserving previous entries.

### `git:setup` -- Interactive configuration

[](#gitsetup----interactive-configuration)

```
php artisan git:setup
```

The wizard walks you through every configurable option:

1. **AI provider** -- Anthropic API, OpenAI API, or Claude Code CLI
2. **Language** -- English, Portuguese (Brazil), Spanish, French, German, Italian, Japanese, Korean, or Chinese
3. **Scopes** -- Define allowed scopes for your project (e.g., `auth`, `api`, `ui`, `database`)
4. **Types** -- Restrict which commit types are allowed (e.g., only `feat`, `fix`, `docs`)
5. **Body preference** -- How the AI handles commit message body (auto, always, never)
6. **Git hook** -- Install a `commit-msg` hook that rejects non-conventional commits

After setup, it writes `config/git-ai.php` and shows the environment variables you need to add to `.env`.

Configuration
-------------

[](#configuration)

All options in `config/git-ai.php`:

```
return [

    // AI provider: 'anthropic', 'openai', or 'claude-code'
    'provider' => env('GIT_AI_PROVIDER', 'anthropic'),

    // AI model override (null = provider default)
    // Examples: 'claude-sonnet-4-5-20250929', 'gpt-4o', etc.
    'model' => env('GIT_AI_MODEL'),

    // Language for commit messages and changelog entries
    // Supported: 'en', 'pt-BR', 'es', 'fr', 'de', 'it', 'ja', 'ko', 'zh'
    'language' => env('GIT_AI_LANGUAGE', 'en'),

    // Allowed commit scopes (empty array = any scope allowed)
    // The AI will only use scopes from this list
    // Example: ['auth', 'api', 'ui', 'database', 'config']
    'scopes' => [],

    // Allowed commit types (empty array = all Conventional Commits types allowed)
    // The AI will only use types from this list
    // Example: ['feat', 'fix', 'docs', 'refactor', 'test']
    'types' => [],

    // Maximum diff size sent to the AI (in characters)
    // Diffs larger than this are truncated with a warning
    'max_diff_size' => env('GIT_AI_MAX_DIFF_SIZE', 15000),

    // Commit message settings
    'commit' => [

        // Body behavior: 'auto' (AI decides), 'always' (AI must include), 'never' (stripped from output)
        'body' => env('GIT_AI_COMMIT_BODY', 'auto'),

        // Footer settings
        'footer' => [

            // Whether to include the BREAKING CHANGE footer when applicable
            'breaking_change' => true,

            // Whether to include a "Co-Authored-By" trailer in commit messages
            // Set to false to prevent AI attribution lines in commits
            'co_authored_by' => env('GIT_AI_CO_AUTHORED_BY', false),

            // Custom footer lines to append to every commit message
            // Example: ['Signed-off-by: Name ']
            'lines' => [],
        ],
    ],

    // Named presets that bundle body + footer settings
    // Built-in templates: 'minimal', 'detailed'
    'templates' => [

        // Default template (null = no template, use 'commit' settings directly)
        'default' => env('GIT_AI_TEMPLATE'),

        // Custom template definitions
        'presets' => [
            // 'my-team' => [
            //     'body' => 'always',
            //     'footer' => [
            //         'breaking_change' => true,
            //         'co_authored_by' => false,
            //         'lines' => ['Signed-off-by: Team '],
            //     ],
            // ],
        ],
    ],

    // Changelog generation settings
    'changelog' => [

        // File path relative to project root
        'path' => 'CHANGELOG.md',

        // Include emojis in section titles (e.g., "### ✨ Features")
        'with_emojis' => true,
    ],

    // Git hook settings
    'hook' => [

        // Whether the commit-msg validation hook is enabled
        'enabled' => false,

        // When true, rejects non-conventional commits
        // When false, only displays a warning
        'strict' => true,
    ],

];
```

### Environment variables

[](#environment-variables)

VariableDescriptionDefault`GIT_AI_PROVIDER`AI provider (`anthropic`, `openai`, `claude-code`)`anthropic``GIT_AI_MODEL`AI model overrideProvider default`GIT_AI_LANGUAGE`Commit message language`en``GIT_AI_MAX_DIFF_SIZE`Max diff size in characters`15000``GIT_AI_COMMIT_BODY`Body behavior (`auto`, `always`, `never`)`auto``GIT_AI_CO_AUTHORED_BY`Include Co-Authored-By trailer`false``GIT_AI_TEMPLATE`Default commit template name--`ANTHROPIC_API_KEY`Anthropic API key (when provider is `anthropic`)--`OPENAI_API_KEY`OpenAI API key (when provider is `openai`)--Commit Templates
----------------

[](#commit-templates)

Templates bundle body and footer preferences into named presets. They're entirely optional -- without a template, the `commit` config section is used directly.

### Built-in templates

[](#built-in-templates)

TemplateBodyBREAKING CHANGE footerUse case`minimal`NeverNoQuick, one-line commits`detailed`AlwaysYesThorough commits with full context### Using templates

[](#using-templates)

```
# Use a built-in template
php artisan git:commit --template=minimal

# Override body on the fly
php artisan git:commit --no-body

# Add custom footers
php artisan git:commit --footer="Signed-off-by: Name "
php artisan git:commit --footer="Reviewed-by: Alice" --footer="Tested-by: Bob"

# Combine options
php artisan git:commit --template=detailed --footer="Signed-off-by: Team "
```

### Set a default template

[](#set-a-default-template)

In your `.env`:

```
GIT_AI_TEMPLATE=minimal
```

Or in `config/git-ai.php`:

```
'templates' => [
    'default' => 'minimal',
],
```

### Custom templates

[](#custom-templates)

Define your own presets in `config/git-ai.php`:

```
'templates' => [
    'default' => null,
    'presets' => [
        'my-team' => [
            'body' => 'always',
            'footer' => [
                'breaking_change' => true,
                'co_authored_by' => false,
                'lines' => ['Signed-off-by: Team '],
            ],
        ],
        'quick' => [
            'body' => 'never',
            'footer' => [
                'breaking_change' => false,
                'lines' => [],
            ],
        ],
    ],
],
```

Then use it:

```
php artisan git:commit --template=my-team
```

### Disabling Co-Authored-By

[](#disabling-co-authored-by)

By default, the `Co-Authored-By` trailer is **not** included in commit messages. If you want to enable it:

```
// config/git-ai.php
'commit' => [
    'footer' => [
        'co_authored_by' => true,
    ],
],
```

Or via environment variable:

```
GIT_AI_CO_AUTHORED_BY=true
```

When enabled, commits will include a trailer like:

```
Co-Authored-By: Claude

```

Set it to `false` (default) to keep commits clean without AI attribution.

Git Hook
--------

[](#git-hook)

The package includes an optional `commit-msg` git hook that validates commit messages against the Conventional Commits specification.

**What it validates:**

- The message must match the format: `(): `
- The type must be one of: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
- The first line must not exceed 72 characters
- Merge commits, reverts, fixups, and squashes are automatically allowed

**Install the hook:**

```
# Via the setup wizard
php artisan git:setup

# Or manually copy the hook file
cp vendor/tharlesamaro/laravel-git-ai/stubs/commit-msg .git/hooks/commit-msg
chmod +x .git/hooks/commit-msg
```

**Example of a rejected commit:**

```
$ git commit -m "updated stuff"

Invalid commit message format!

Your message:
  updated stuff

Expected format:
  ():

Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

Examples:
  feat(auth): add OAuth2 login support
  fix: resolve null pointer in user service
  docs(readme): update installation instructions

Tip: Use 'php artisan git:commit' to generate valid messages automatically.

```

Conventional Commits
--------------------

[](#conventional-commits)

This package follows the [Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) specification:

```
():

[optional body]

[optional footer(s)]

```

### Supported types

[](#supported-types)

TypeEmojiDescription`feat`✨A new feature`fix`🐛A bug fix`docs`📚Documentation only changes`style`💎Code style changes (formatting, semicolons, etc.)`refactor`♻️Code refactoring (no feature or fix)`perf`⚡Performance improvements`test`🧪Adding or fixing tests`build`📦Build system or dependency changes`ci`🔧CI configuration changes`chore`🔨Other changes (tooling, configs, etc.)`revert`⏪Reverts a previous commit### Breaking changes

[](#breaking-changes)

Breaking changes are indicated by:

- An `!` after the type/scope: `feat(api)!: remove deprecated endpoints`
- A `BREAKING CHANGE:` footer in the body

The AI detects breaking changes automatically from the diff and sets `is_breaking_change` accordingly.

Architecture
------------

[](#architecture)

The package uses a service abstraction layer (`AiService` contract) that allows swapping between providers without changing command logic:

- **`AgentAiService`** -- Uses the Laravel AI SDK agents with structured output for API-based providers (Anthropic, OpenAI)
- **`ClaudeCodeAiService`** -- Invokes the `claude` CLI as a subprocess for users with a Claude subscription

The provider is resolved at runtime based on `config('git-ai.provider')`. Both implementations return the same structured array format, ensuring consistent behavior regardless of the provider.

Testing
-------

[](#testing)

```
composer test
```

This package uses [Pest PHP](https://pestphp.com/) for testing. To run with coverage:

```
composer test-coverage
```

Using Docker:

```
docker compose run --rm test
```

Contributing
------------

[](#contributing)

Contributions are welcome! Please follow Conventional Commits for your commit messages.

1. Fork the repository
2. Create your feature branch (`git checkout -b feat/amazing-feature`)
3. Commit your changes (`php artisan git:commit` 😄)
4. Push to the branch (`git push origin feat/amazing-feature`)
5. Open a Pull Request

License
-------

[](#license)

The MIT License (MIT). See [LICENSE](LICENSE) for details.

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance82

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

97d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/98f16d6943e63d9c5aa2cf6178c9716fa50578e8f8b66ad7b652214e0bcb4b82?d=identicon)[tharlesamaro](/maintainers/tharlesamaro)

---

Tags

laravelaiopenaigitcommitanthropicchangelogconventional-commits

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/tharlesamaro-laravel-git-ai/health.svg)

```
[![Health](https://phpackages.com/badges/tharlesamaro-laravel-git-ai/health.svg)](https://phpackages.com/packages/tharlesamaro-laravel-git-ai)
```

###  Alternatives

[marcocesarato/php-conventional-changelog

Generate changelogs and release notes from a project's commit messages and metadata and automate versioning with semver.org and conventionalcommits.org

2511.3M109](/packages/marcocesarato-php-conventional-changelog)[guanguans/ai-commit

Automagically generate conventional git commit message with AI. - 使用 AI 自动生成约定式 git 提交信息。

39231.2k10](/packages/guanguans-ai-commit)[salehhashemi/laravel-intelli-git

An intelligent Git helper package for Laravel applications. It utilizes OpenAI's GPT to analyze your Git repository, providing features such as automatic generation of commit messages based on staged changes.

131.5k](/packages/salehhashemi-laravel-intelli-git)[soukicz/llm

LLM client with support for cache, tools and async requests

445.6k](/packages/soukicz-llm)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)