smart-commit: AI-powered git commits using Claude Code CLI

README.md

smart-commit

AI-powered git commits using Claude Code CLI

A zsh function that analyzes your staged and unstaged changes, then creates logical, atomic commits following the Conventional Commits specification.

What It Does

When you run smart-commit, Claude will:

1. Analyze your changes - Runs git status and git diff to understand what you've modified
2. Plan the commits - Groups related changes into logical, atomic commits
3. Create commits - Stages files with git add and commits with proper conventional commit messages
4. Verify - Checks git status after each commit to confirm success

Safety Features

The function uses Claude Code's permission system to restrict what the AI can do:

Allowed:

• git status - View repository state
• git diff - See changes
• git add - Stage files
• git commit - Create commits
• Read - Read file contents for context

Blocked (for safety):

• git push - Won't push to remote
• git reset / git revert - Won't undo commits
• git rebase / git merge - Won't modify history
• git checkout / git branch - Won't switch branches
• rm / mv - Won't delete or move files
• Write / Edit - Won't modify your code

Installation

Prerequisites

1. Claude Code CLI - Install from github.com/anthropics/claude-code

   npm install -g @anthropic-ai/claude-code

2. Git - Ensure git is installed and configured

Setup

1. Open your zsh configuration file:

   # macOS / Linux
   nano ~/.zshrc
   # or use your preferred editor
   code ~/.zshrc

2. Add the smart-commit function (copy from smart-commit.zsh)

3. Reload your shell configuration:

   source ~/.zshrc

Usage

Basic Usage

Navigate to any git repository with changes and run:

smart-commit

Claude will analyze all changes and create appropriate commits.

With Context

Provide additional context to help Claude understand your changes:

smart-commit "refactoring the authentication flow"

smart-commit "bug fix for issue #123"

smart-commit "adding new user dashboard feature"

Example Session

$ git status
On branch feature/auth
Changes not staged for commit:
  modified:   src/auth/login.ts
  modified:   src/auth/logout.ts
  modified:   src/utils/validation.ts
  modified:   README.md

$ smart-commit "updated authentication"

# Claude will:
# 1. Examine the diffs
# 2. Announce its commit strategy
# 3. Create commits like:
#    - feat(auth): add session expiry handling
#    - refactor(utils): extract email validation
#    - docs(readme): update auth setup instructions

Conventional Commits Format

The function enforces these commit types:

Type	Description
feat	New feature
fix	Bug fix
docs	Documentation changes
style	Code style (formatting, semicolons, etc.)
refactor	Code refactoring (no feature/fix)
perf	Performance improvements
test	Adding or updating tests
build	Build system or dependencies
ci	CI/CD configuration
chore	Maintenance tasks

Format: <type>(<scope>): <description>

Examples:

• feat(api): add user profile endpoint
• fix(auth): resolve token refresh race condition
• docs(contributing): add PR guidelines

Customization

Change the Model

The function uses haiku (fast and cheap) by default. For more complex analysis, change to sonnet:

--model="sonnet"

Adjust the System Prompt

Modify the --append-system-prompt section to change commit style, add team conventions, or adjust the workflow.

Tips

1. Review before pushing - The function doesn't push, so always review commits with git log before pushing

2. Use context wisely - Providing context helps Claude make better grouping decisions

3. Works best with related changes - If you have many unrelated changes, consider committing in batches

4. Check the plan - Claude announces its strategy before committing - interrupt if needed

License

MIT - Feel free to modify and share!

smart-commit.zsh

# --------------------------------------------------------------------------------------------------------------
# smart-commit - AI-Powered Git Commits with Claude Code
# --------------------------------------------------------------------------------------------------------------
# A zsh function that uses Claude Code to analyze your git changes and create
# logical, atomic commits following conventional commits format.
#
# Requirements:
#   - Claude Code CLI installed (https://github.com/anthropics/claude-code)
#   - Git installed
#   - zsh shell
#
# Installation:
#   Add this function to your ~/.zshrc file, then run: source ~/.zshrc
# --------------------------------------------------------------------------------------------------------------

smart-commit() {
    local context="${1:-}"
    local prompt="Analyze git changes and create logical, atomic commits using conventional commits format."

    if [ -n "$context" ]; then
        prompt="$prompt Context: $context"
    fi

    claude "$prompt" \
    --allowedTools "Bash(git status)" \
    "Bash(git diff:*)" \
    "Bash(git add:*)" \
    "Bash(git commit:*)" \
    "Read" \
    --disallowedTools "Bash(git push:*)" \
    "Bash(git reset:*)" \
    "Bash(git revert:*)" \
    "Bash(git clean:*)" \
    "Bash(git rebase:*)" \
    "Bash(git merge:*)" \
    "Bash(git checkout:*)" \
    "Bash(git branch:*)" \
    "Bash(rm:*)" \
    "Bash(mv:*)" \
    "Write" \
    "Edit" \
    --model="haiku" \
    --append-system-prompt "STRICT RULES:
1. ONLY use git status, git diff, git add, and git commit commands
2. Use conventional commits: feat|fix|docs|style|refactor|perf|test|build|ci|chore
3. Format: <type>(<scope>): <description> (max 50 chars)
4. Group related changes in one commit
5. Keep commits atomic and focused
6. One logical change per commit
7. After each commit, verify with git status

WORKFLOW:
- Examine changes with git status and git diff
- Plan commits (announce your strategy)
- Execute commits one by one
- Provide summary of completed commits

EXAMPLES:
- feat(auth): add JWT validation
- fix(api): resolve memory leak
- docs(readme): update setup instructions
- refactor(utils): extract validation logic"
}