@blendsdk/git-commit-agent

Git Commit Agent

AI-powered git commit message generator using LangChain and OpenAI. Automatically analyzes code changes and creates high-quality conventional commit messages.

Features

• 🤖 AI-Powered Analysis - Uses OpenAI to understand code changes
• 📝 Conventional Commits - Generates standardized commit messages
• 🔍 Smart Detection - Identifies commit type, scope, and impact
• ⚙️ Flexible Configuration - CLI options, environment variables, and global config
• 🛡️ Error Handling - Comprehensive error handling with recovery suggestions
• 🌍 Global Configuration - Support for user-wide settings via ~/.agent-config

Installation

Option 1: NPM/Yarn (Recommended)

# Using npm
npm install -g @blendsdk/git-commit-agent

# Using yarn
yarn global add @blendsdk/git-commit-agent

Option 2: From Source

# Clone the repository
git clone https://github.com/blendsdk/git-commit-agent.git
cd git-commit-agent

# Install dependencies
yarn install

# Build
yarn build

# Link globally for testing
yarn link

Quick Start

# Navigate to your git repository
cd your-project

# Make some changes
# ... edit files ...

# Run the agent
git-commit-agent

The agent will:

• Analyze all changes in your repository
• Generate a comprehensive conventional commit message
• Stage all changes (configurable)
• Create the commit with proper multi-line formatting

Configuration

Environment Variables

Create a .env file in your project root or ~/.agent-config in your home directory:

# Required
OPENAI_API_KEY=your_openai_api_key_here

# Optional - Model configuration
OPENAI_MODEL=gpt-4

# Optional - LangChain configuration
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your_langchain_api_key

# Optional - Commit format defaults
COMMIT_TYPE=feat
COMMIT_SCOPE=api
COMMIT_SUBJECT_MAX_LENGTH=72
COMMIT_DETAIL_LEVEL=normal
COMMIT_FILE_BREAKDOWN=true

# Optional - Behavior defaults
AUTO_STAGE=all
PUSH=false
SKIP_VERIFICATION=false
CONVENTIONAL_STRICT=true

# Optional - Execution defaults
DRY_RUN=false
VERBOSE=false

Global Configuration

For user-wide settings, create ~/.agent-config:

# Linux/Mac
echo "OPENAI_API_KEY=your_key_here" > ~/.agent-config

# Windows
echo OPENAI_API_KEY=your_key_here > %USERPROFILE%\.agent-config

Note: Local .env files override global settings.

Configuration Priority

Configuration values are merged from three sources:

• CLI Arguments (highest priority)
• Environment Variables (from .env file)
• Built-in Defaults (lowest priority)

Usage

Basic Commands

# Use default configuration
git-commit-agent

# Preview commit message without committing
git-commit-agent --dry-run

# Enable verbose output for debugging
git-commit-agent --verbose

# Get help
git-commit-agent --help

# Show version
git-commit-agent --version

CLI Options

Commit Message Format

--commit-type <type>
Force a specific commit type instead of letting the agent determine it.

Choices: feat, fix, refactor, docs, test, build, ci, perf, style, chore

git-commit-agent --commit-type feat

--scope <scope>
Set the commit scope (e.g., auth, api, ui).

git-commit-agent --scope auth

--subject-max-length <number>
Maximum length for the commit subject line (default: 72).

git-commit-agent --subject-max-length 50

--detail-level <level>
Control the level of detail in the commit message body.

Choices: brief, normal, detailed (default: normal)

• brief: Minimal description (1-2 sentences)
• normal: Standard description with key changes
• detailed: Comprehensive description with file-by-file breakdown

git-commit-agent --detail-level detailed

--file-breakdown / --no-file-breakdown
Include or exclude file-by-file breakdown in the commit body (default: true).

git-commit-agent --no-file-breakdown

Behavior Controls

--auto-stage <mode>
Control automatic staging behavior before commit.

Choices: all, modified, none (default: all)

• all: Stage all changes including untracked files (git add .)
• modified: Stage only modified and deleted files (git add -u)
• none: Don't stage anything, commit only what's already staged

git-commit-agent --auto-stage modified

--push
Push changes to remote repository after committing (default: false).

When this flag is set, the system will automatically push the commit to the remote repository after successfully committing locally. Without this flag, commits remain local only.

git-commit-agent --push

--no-verify
Skip commit verification hooks (pre-commit, commit-msg) (default: false).

git-commit-agent --no-verify

--conventional-strict
Enforce strict conventional commit format (default: true).

git-commit-agent --conventional-strict

Execution Options

--dry-run
Analyze changes and generate commit message without actually committing (default: false).

git-commit-agent --dry-run

--verbose
Enable verbose logging to see detailed execution information (default: false).

git-commit-agent --verbose

--config <path>
Path to custom configuration file (future feature).

git-commit-agent --config ./custom-config.json

Usage Examples

Basic Usage

# Use all defaults
git-commit-agent

# Preview commit message without committing
git-commit-agent --dry-run

# Enable verbose output for debugging
git-commit-agent --verbose

Commit Message Customization

# Force specific commit type and scope
git-commit-agent --commit-type feat --scope auth

# Brief commit message without file breakdown
git-commit-agent --detail-level brief --no-file-breakdown

# Detailed commit with longer subject line
git-commit-agent --detail-level detailed --subject-max-length 100

# Quick fix with minimal detail
git-commit-agent --commit-type fix --detail-level brief

Staging Control

# Stage all files including untracked (default)
git-commit-agent --auto-stage all

# Only stage modified files
git-commit-agent --auto-stage modified

# Only commit already staged files
git-commit-agent --auto-stage none

Advanced Workflows

# Complete workflow: stage all, commit, and push
git-commit-agent --auto-stage all --push

# Complete workflow: stage all and commit (without pushing)
git-commit-agent --auto-stage all

# Skip pre-commit hooks
git-commit-agent --no-verify

# Dry run with verbose output to see what would happen
git-commit-agent --dry-run --verbose

# Feature commit with detailed breakdown
git-commit-agent --commit-type feat --scope api --detail-level detailed

Team Workflows

# Consistent brief commits for the team
git-commit-agent --detail-level brief --subject-max-length 50

# Detailed commits for major features
git-commit-agent --detail-level detailed --commit-type feat

# Quick fixes without verification
git-commit-agent --commit-type fix --no-verify --detail-level brief

Configuration Presets

Preset 1: Quick Commits

For rapid development with minimal commit messages:

git-commit-agent --detail-level brief --no-file-breakdown

Or in .env:

COMMIT_DETAIL_LEVEL=brief
COMMIT_FILE_BREAKDOWN=false
AUTO_STAGE=all

Preset 2: Detailed Documentation

For comprehensive commit history:

git-commit-agent --detail-level detailed --file-breakdown --subject-max-length 72

Or in .env:

COMMIT_DETAIL_LEVEL=detailed
COMMIT_FILE_BREAKDOWN=true
COMMIT_SUBJECT_MAX_LENGTH=72

Preset 3: CI/CD Pipeline

For automated commits in CI/CD:

git-commit-agent --auto-stage all --no-verify --push --detail-level normal

Or in .env:

AUTO_STAGE=all
SKIP_VERIFICATION=true
PUSH=true
COMMIT_DETAIL_LEVEL=normal

Commit Message Format

The agent generates commit messages following the Conventional Commits specification:

<type>(<scope>): <subject>

<body>

<footer>

Commit Types

Type	Description
feat	New feature
fix	Bug fix
docs	Documentation changes
style	Code style changes (formatting)
refactor	Code refactoring
perf	Performance improvements
test	Adding or updating tests
build	Build system changes
ci	CI configuration changes
chore	Other changes

Example Output

feat(auth): add OAuth2 authentication support

- Implement OAuth2 flow with Google and GitHub providers
- Add token refresh mechanism
- Create user session management
- Update authentication middleware to support OAuth tokens

This enables users to sign in using their existing social accounts,
improving user experience and reducing friction in the signup process.

Closes #234

Troubleshooting

"Not a git repository" Error

Make sure you're in a git repository:

git init  # If starting a new repo

"OPENAI_API_KEY not found" Error

Set your API key:

export OPENAI_API_KEY=your_key_here
# Or add to .env file

"No changes to commit" Error

Make sure you have uncommitted changes:

git status  # Check for changes

Commit message too long

Reduce --subject-max-length or use --detail-level brief:

git-commit-agent --subject-max-length 50 --detail-level brief

Wrong files staged

Use --auto-stage none and manually stage files first:

git add file1.js file2.js
git-commit-agent --auto-stage none

Pre-commit hooks failing

Use --no-verify to skip hooks (use cautiously):

git-commit-agent --no-verify

Need to see what's happening

Use --verbose and --dry-run together:

git-commit-agent --verbose --dry-run

Build Errors (when installing from source)

# Clear node_modules and reinstall
rm -rf node_modules yarn.lock
yarn install
yarn build

Tips and Best Practices

• Use .env for team defaults: Set common configuration in .env and commit it to your repository
• Override with CLI for special cases: Use CLI arguments for one-off changes
• Dry run first: Use --dry-run to preview the commit message before committing
• Verbose for debugging: Enable --verbose when troubleshooting issues
• Consistent subject length: Stick to 72 characters for better GitHub display
• Detail level by context: Use brief for small changes, detailed for major features

Documentation

• DEVELOPMENT.md - Development guide, architecture, and contributing

License

ISC License - see LICENSE file for details.

Acknowledgments

• LangChain - Framework for LLM applications
• OpenAI - AI model provider
• Conventional Commits - Commit message specification

Support

For issues, questions, or contributions, please visit the GitHub repository.

Note: Remember to replace repository URLs with your actual GitHub repository.