🤖 AI Commit Toolkit

One-command setup for AI-powered conventional commits with OpenAI integration, automated versioning, and seamless deployment workflows.

⚡ Quick Start

# Navigate to your project
cd your-project

# Install locally (recommended for customization)
npm install --save-dev @cirrusinvicta/ai-commit-toolkit

# Setup AI commit toolkit
npx ai-commit-toolkit setup

# Set your OpenAI API key
export OPENAI_API_KEY="your-api-key-here"

# Start using AI-powered commits
git add .
git commit  # AI generates your commit message automatically!

🎯 What You Get

• ✅ Intelligent AI commit message generation using OpenAI GPT-4o-mini with comprehensive change analysis
• ✅ Smart file filtering automatically excludes node_modules/, package-lock.json, and other noise
• ✅ Multi-file change handling generates cohesive messages for complex commits with multiple files
• ✅ Conventional commit format enforcement with commitlint integration
• ✅ Husky hooks integration for seamless git workflow automation
• ✅ Centralized configuration system for easy customization and team consistency
• ✅ Accurate length validation correctly validates subject line length (not total message)
• ✅ Semantic versioning support with automated releases
• ✅ Robust fallback mechanisms when AI is unavailable
• ✅ Comprehensive testing suite with 35+ validation tests

📦 Installation

Project-Specific Installation (Recommended)

# Navigate to your project directory
cd your-project

# Install as a dev dependency
npm install --save-dev @cirrusinvicta/ai-commit-toolkit

# Setup the toolkit in your project
npx ai-commit-toolkit setup

Why Local Installation?

• ✅ Project-specific configuration - Each project can have customized AI prompts and settings
• ✅ Version consistency - Team members use the same toolkit version
• ✅ Better customization - Edit configs/ai-prompts.conf to tailor AI behavior for your project
• ✅ No global conflicts - Avoid version conflicts between different projects

Global Installation (Alternative)

npm install -g @cirrusinvicta/ai-commit-toolkit
ai-commit-toolkit setup --type generic  # or ansible, vue, react

Note on Project Types: Currently, all project types (generic, ansible, vue, react) use identical configurations and templates. The --type parameter is provided for future extensibility when project-specific customizations are added. For now, using any type will result in the same setup.

🛠️ Usage

Automated Usage (Recommended)

# Make your changes
git add .

# Commit with AI (hook automatically generates message)
git commit
# ✨ Editor opens with AI-generated conventional commit message

Manual AI Generation

# Generate and commit in one step
npx ai-commit

# Interactive helper with guidance
npx ai-commit-helper

# Test your setup
npx ai-commit-test

🧪 Testing

# Comprehensive validation (35+ tests total)
npm test

# Individual test suites
npm run test:config      # Configuration system (23 tests)
npx ai-commit-test      # Basic validation (12 tests)

# Test with actual commit generation
npx ai-commit-test --create-test-file

⚙️ Configuration

The AI Commit Toolkit uses a centralized configuration system for easy customization.

Project Types

The toolkit supports different project types via the --type parameter:

• generic (default) - Universal configuration suitable for any project
• ansible - For Ansible playbooks and roles
• vue - For Vue.js applications
• react - For React applications

Current Status: All project types currently use identical configurations. The framework exists for future expansion when project-specific templates and prompts are added.

🚀 Recent Improvements

Enhanced AI Commit Generation

• Comprehensive Change Analysis: No more truncated diffs - AI now sees full context of your changes
• Smart Multi-File Handling: Generates cohesive messages for complex commits with many files
• Intelligent File Filtering: Automatically excludes noise files like node_modules/ and package-lock.json
• Accurate Length Validation: Correctly validates only the subject line length (72 chars) instead of total message
• Better Commit Categorization: Improved logic for choosing appropriate conventional commit types and scopes

Example: Before vs After

Before (limited context):

chore(husky): add commit-msg and prepare-commit-msg hooks
⚠️ Warning: Message exceeds 100 characters (false positive)

After (full context):

chore(setup): initialize AI commit toolkit

- Add Husky hooks for commit message validation
- Configure commitlint for conventional commits
- Create environment and configuration files
- Install project dependencies and scripts

AI Prompts Configuration

After setup, all AI prompts and settings are stored in configs/ai-prompts.conf:

# Main AI commit generation prompt
AI_COMMIT_PROMPT="Generate a conventional commit message..."

# OpenAI API Configuration
OPENAI_MODEL="gpt-4o-mini"
OPENAI_MAX_TOKENS=100
OPENAI_TEMPERATURE=0.3

# File exclusion patterns (automatically filtered from AI context)
AI_COMMIT_EXCLUDE="node_modules/ package-lock.json .env"

# Git ignore patterns (what should never be committed)
# Note: package-lock.json is NOT excluded - it should be committed for reproducible builds
GITIGNORE_EXCLUDE="node_modules .env"

# Commit message validation
MAX_COMMIT_LENGTH=100
WARN_COMMIT_LENGTH=72

Customizing Prompts

To customize the AI prompts for your project:

1. After setup: Edit configs/ai-prompts.conf in your project root
2. Modify prompts: Update AI_COMMIT_PROMPT to match your project's style and requirements
3. Adjust exclusions: Add patterns to AI_COMMIT_EXCLUDE to filter out files you don't want in AI context
4. Fine-tune settings: Change OpenAI model, token limits, or validation rules
5. Test changes: Run npx ai-commit-test to validate your configuration

Example Customizations:

# For a React project
AI_COMMIT_EXCLUDE="node_modules/ package-lock.json .env build/ dist/"

# For more detailed messages
OPENAI_MAX_TOKENS=150
OPENAI_TEMPERATURE=0.4

# For stricter length limits
MAX_COMMIT_LENGTH=72
WARN_COMMIT_LENGTH=60

Environment Variables

Required:

• OPENAI_API_KEY: Your OpenAI API key

Optional:

• OPENAI_MODEL: Override the default model (default: gpt-4o-mini)
• OPENAI_MAX_TOKENS: Override token limit (default: 100)

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• 📖 Documentation
• 🐛 Issue Tracker

Made with ❤️ by Cirrus Invicta

Transform your commit workflow with intelligent AI that understands your full codebase context and generates meaningful, accurate commit messages for even the most complex changes.