AI Commit Guard

🤖 AI-powered pre-commit code review tool that automatically checks your code changes before commit using OpenAI GPT-4 or Anthropic Claude.

✨ Features

• 🔍 Smart Detection - Only reviews staged .js, .ts, .jsx, .tsx, .vue, .py files
• 🚀 Lightning Fast - Cached results for unchanged code
• 🎯 Custom Rules - Define your own coding standards
• 🔄 Multi-Provider - Works with OpenAI GPT-4 or Anthropic Claude
• 🛡️ Zero Config - Works out of the box with sensible defaults
• 📝 Detailed Feedback - Get specific line-by-line suggestions

🚀 Quick Start

1. Install Globally

npm install -g ai-commit-guard

2. Setup in Your Project

# Install husky (if not already installed)
npm install --save-dev husky
npx husky init

# Add AI Guard to pre-commit hook
echo "npx ai-commit-guard" > .husky/pre-commit
chmod +x .husky/pre-commit

3. Set Your AI API Key

Option A: OpenAI (Recommended)

export OPENAI_API_KEY="sk-your-openai-key-here"

Option B: Anthropic Claude

export CLAUDE_API_KEY="sk-ant-your-claude-key-here"
export AI_PROVIDER="claude"

4. That's It! 🎉

Now AI Guard will automatically review your code on every commit:

git add .
git commit -m "feat: add user authentication"
# → AI Guard automatically reviews your changes

📋 Custom Rules (Optional)

Create a .code-rules.md file in your project root to define custom coding standards:

# My Code Review Rules

## Magic Strings
- No string literals in code, use constants
- Event properties should use EVENT_FIELDS constant

## Functions
- Functions should not exceed 20 lines
- Use descriptive function names
- Follow single responsibility principle

## Variables
- Use camelCase for variables
- Boolean variables should start with is/has/can/should
- No single letter variables except for loops

## Error Handling
- Always use try-catch for async operations
- Log errors with appropriate context

## Examples

❌ **Bad:**
```javascript
event['status'] = 'active';
function getData() { /* 30 lines of mixed responsibilities */ }
let x = true;

✅ Good:

const EVENT_FIELDS = { STATUS: 'status' };
event[EVENT_FIELDS.STATUS] = 'active';

function fetchUserData() { /* single responsibility */ }
function processUserData() { /* separate concern */ }

let isUserActive = true;

## 🛠️ Usage

### Automatic Mode (Recommended)
AI Guard runs automatically when you commit:

```bash
git add src/
git commit -m "refactor: improve error handling"
# 🔍 Checking staged files...
# 📝 Reviewing 3 files...
# 🤖 Sending to AI for review...
# ✅ Code review passed!

Manual Mode

Run review without committing:

npx ai-commit-guard

Test Mode

Check if everything is working:

# Test with sample code
npx ai-commit-guard --test

📊 Example Output

✅ Passing Review

🔍 Checking staged files...
📝 Reviewing 2 files...
🤖 Sending to AI for review...
✅ Code review passed!

💡 Suggestions:
• Consider adding JSDoc comments for public functions
• Variable naming looks great, well done!

❌ Failing Review

🔍 Checking staged files...
📝 Reviewing 3 files...
🤖 Sending to AI for review...
❌ Code review failed!

Issues found:
• src/utils.js: Magic string 'status' on line 15
  Fix: Use EVENT_FIELDS.STATUS constant

• src/api.js: Function getUserData() is 25 lines long
  Fix: Split into fetchUser() and processUser() functions

• src/components/User.tsx: Variable 'x' is not descriptive
  Fix: Rename to 'isUserLoggedIn' or similar

⚙️ Configuration

Environment Variables

Files

🎯 Supported File Types

• JavaScript: .js
• TypeScript: .ts
• React: .jsx, .tsx
• Vue: .vue
• Python: .py

🔧 Advanced Usage

Different Rules Per Project

# Create project-specific rules
echo "# Strict React Rules\n- All components must have PropTypes" > .code-rules.md

Temporary Disable

# Skip AI review for this commit
git commit -m "docs: update README" --no-verify

Clear Cache

# Remove cached reviews
rm -rf .ai-guard-cache

🤔 Why AI Commit Guard?

🆚 Comparison

🐛 Troubleshooting

Common Issues

"No AI API key found"

# Check if key is set
echo $OPENAI_API_KEY

# Set the key
export OPENAI_API_KEY="sk-your-key-here"

# Make it permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export OPENAI_API_KEY="sk-your-key-here"' >> ~/.bashrc

"Not a git repository"

# Initialize git first
git init
git add .
git commit -m "initial commit"

"No staged files to review"

# Make sure files are staged
git status
git add .

"AI connection failed"

# Check your API key and internet connection
curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models

Performance Tips

• 🏃‍♂️ Enable caching: Cache is enabled by default
• 📁 Stage only what you need: git add specific-file.js
• 🎯 Use specific rules: More specific rules = faster reviews
• 🧹 Clean cache periodically: rm -rf .ai-guard-cache

📈 Roadmap

• Support for more file types (Go, Rust, C++)
• Integration with popular IDEs
• Team dashboards and analytics
• Custom AI model fine-tuning
• Slack/Discord notifications
• CI/CD pipeline integration

🤝 Contributing

We love contributions! Here's how to help:

1. 🍴 Fork the repository
2. 🌱 Create your feature branch: git checkout -b my-feature
3. ✅ Commit your changes: git commit -m 'Add cool feature'
4. 🚀 Push to the branch: git push origin my-feature
5. 📝 Open a Pull Request

📄 License

MIT © Adem Alkan

Made with ❤️ for better code quality

Star ⭐ this repo if it helps you write better code!