🌱 git-curate

Effortlessly generate clear, meaningful Git commit messages with AI

✨ Overview

git-curate is a lightweight CLI tool leveraging AI (via Codex CLI, Claude Code CLI, or Claude Code SDK) to automatically generate concise, standardized, and meaningful Git commit messages.

No more ambiguous commit histories. Just simple, clean, and informative commits, intelligently curated by AI.

🚀 Quick Start

Using NPX

npm install -g @taptap/git-curate

Now, you can simply run:

git curate [<additional instructions>]

⚡ Recommended: Using Bun

While npx works, it's highly recommended to use Bun for faster and more efficient execution.

After installing Bun, git-curate will automatically use the Bun bytecode version for optimal performance (much more faster). You do NOT need to run bun add -d @taptap/git-curate to reinstall.

🛠 Requirements

• Node.js and npm installed (or Bun for better performance)
• Either Codex CLI, Claude Code CLI, or Claude Code SDK installed and available in your $PATH, logged in, and configured.

⚠️ Git Worktree Compatibility

Important: If you're using git worktrees with relativeworktrees extension, use Claude Code CLI instead of Codex CLI.

Codex CLI may encounter issues accessing staged files in git worktree environments due to limited git repository support. Claude Code CLI has better environment compatibility and can properly access staged changes in all git configurations.

Recommended configuration for worktree environments:

{
  "tool": {
    "claude-code-cli": {
      "model": "claude-sonnet-4-20250514"
    }
  }
}

⚙️ How it works

1. Stages changes with git add.
2. Generates a commit message by feeding a templated prompt to Codex CLI, Claude Code CLI, or Claude Code SDK.
3. Shows the generated message and prompts for user confirmation.
4. Commits the message if approved, or regenerates if requested.

🎯 Example Usage

Basic Usage

# Stage your changes
git add .

# Let git-curate create a meaningful commit
git curate

Advanced Usage

# Link commit to a specific GitHub issue
git curate -i 1234

# Link commit to multiple GitHub issues
git curate -i 1234,5678

# Mark as breaking change
git curate -b

# Add custom instructions
git curate "focus on performance improvements"

# Test without committing (test mode)
git curate --test

# Test with additional parameters
git curate --test -i 1234 "test message generation"

# Auto-commit without confirmation (bypass interactive mode)
git curate -y

# Auto-commit with issue linking
git curate -y -i 1234 "fix authentication issue"

# Combine issue linking with breaking change
git curate -i 1234 -b "breaking change in authentication API"

Command Options

• -i, --issue-id <ids> - Related GitHub issue IDs (comma-separated)
• -b, --breaking-change - Mark this commit as containing breaking changes
• -y, --yes - Auto-commit without confirmation (bypass interactive mode)
• --test - Generate commit message without committing (test mode)
• -h, --help - Show help message

Interactive Mode

By default, git-curate runs in interactive mode:

1. Generates a commit message based on your staged changes
2. Displays the message in a clear, bordered format
3. Provides options to:
   • ✅ Commit - Accept and commit the message
   • 🔄 Regenerate - Generate a new message with the same parameters

Use arrow keys to navigate and Enter to select an option.

Sample Commit Messages:

# Basic commit

✨ feat(auth): implement JWT token refresh for improved session management

# With single issue

🐛 fix(api): resolve authentication timeout issue (#1234)

# With multiple issues

♻️ refactor(core): optimize database queries for better performance (#1234, #5678)

# Breaking change (using -b flag)

💥 feat(api)!: remove deprecated authentication endpoints (#1234)

- 💥 remove `/v1/auth/legacy` endpoint
- ✨ add new `/v2/auth/token` endpoint with enhanced security
- 📝 update API documentation

💥 BREAKING CHANGE:

- The `/v1/auth/legacy` endpoint has been removed. Use `/v2/auth/token` instead
- Response format has changed: `token` field is now `access_token`

🔖 Customization

You can customize the commit message style by placing configuration files. The configuration loading follows this priority order (later configs override earlier ones):

Configuration Priority

Configuration files are loaded in this order, with later configs overriding earlier ones:

1. Default config: Built-in defaults from the package
2. User-level config: ~/.config/curaterc - Personal preferences
3. Project-level config: <GIT_DIR>/.curaterc - Project-specific settings (highest priority)

Configuration Format

All configuration files use the same JSON format:

{
  "tool": {
    "claude-code-cli": {
      "model": "claude-sonnet-4-20250514"
    }
  },
  "locale": "en-US", // Language locale for commit messages
  "gitmoji": {
    "enabled": true, // Enable Gitmoji support
    "style": "emoji" // Gitmoji style: "emoji", "code", or "entity"
  },
  "scope": {
    "enabled": false, // Enable scope in commit messages
    "default": null // Default scope value if enabled
  },
  "conventionalCommit": {
    "enabled": true, // Enable Conventional Commits support
    "version": "1.0.0" // Conventional Commits specification version
  }
}

Example Configurations

User-level config (~/.config/curaterc):

{
  "tool": {
    "claude-code-cli": {
      "model": "claude-sonnet-4-20250514"
    }
  },
  "locale": "en-US",
  "gitmoji": {
    "enabled": true,
    "style": "emoji"
  },
  "conventionalCommit": {
    "enabled": true
  }
}

Project-level config (<GIT_DIR>/.curaterc):

{
  "tool": {
    "codex-cli": {
      "provider": "OpenAI",
      "model": "gpt-5"
    }
  },
  "gitmoji": {
    "enabled": false
  },
  "scope": {
    "enabled": true,
    "default": "feat"
  }
}

🔧 Troubleshooting

"No staged files found" Error

If you see this error despite having staged files:

❌ No staged files found. Please stage your changes first with 'git add' before running git-curate.

Cause: This typically occurs when using git worktrees with the relativeworktrees extension. Codex CLI cannot access staged files in these environments.

Solution: Switch to Claude Code CLI in your configuration:

# Update your .curaterc file
{
  "tool": {
    "claude-code-cli": {
      "model": "claude-sonnet-4-20250514"
    }
  }
}

Verification: Check if you're using worktrees:

# Check if .git is a file (worktree) vs directory (normal repo)
ls -la .git

# If it shows "gitdir: ../path/to/worktree", you're using worktrees
cat .git

Other Common Issues

• "Command not found": Ensure your chosen AI tool (codex/claude) is installed and in your PATH
• Authentication errors: Run codex login or claude login to authenticate
• Configuration not loading: Check file paths and JSON syntax in .curaterc files

🤝 Contributing

Contributions are welcome! Feel free to submit PRs, issues, or suggestions.

🧪 Development & Testing

For local development and testing without publishing:

# Quick development test (recommended)
bun run dry

# Install dependencies
bun install

# Run checks
bun run chk

# Run tests
bun test

# Build project
bun run build

# Test locally via npm link
npm link

See TESTING.md for comprehensive testing guide.

🚀 Release Process

Releases are automated via GitHub Actions. To publish a new version:

1. Create and push a git tag: git tag v0.2.0 && git push origin v0.2.0
2. GitHub Actions will automatically build, test, and publish to npm

See CLAUDE.md for detailed development guidelines.

📄 License

MIT © TapTap