Commitor — Prototype

A Wizard-of-Oz prototype for testing whether AI-grouped commits are actually useful.

This project reads your git diff, sends it to Gemini, and prints suggested logical commit groups with conventional commit messages. It is intentionally minimal: it never runs git add, git commit, or git push for you.

How to use it

1) Set up your API key

Get a free Gemini API key at Google AI Studio.

Then run:

commitor connect

You'll be prompted to enter your API key. It will be saved to ~/.commitor/config.json for future use.

Alternatively, you can set the GEMINI_API_KEY environment variable:

export GEMINI_API_KEY=AIza-your-key-here

2) Install globally (via npm link)

From the commitor directory, run:

npm link

This makes commitor available as a terminal command. You can then run it from any git repository:

commitor commit

3) Run it in a repo with changes

From any git repo with uncommitted work:

commitor commit                    # full context mode (reads entire files)
commitor commit --fast             # fast mode (diff hunks only)
commitor commit --no-ai            # local grouping by directory (no API call)
commitor commit --squash-merge     # combine all into one commit
commitor commit --staged           # only staged changes
commitor commit --file diff.txt    # analyze a saved diff file

Flags can be combined:

commitor commit --fast --staged    # fast mode on staged changes only
commitor commit --squash-merge --no-ai  # combine into one, group locally

4) Review the suggested commits

Commitor will:

1. Read the diff (git diff by default, or only staged changes with --staged)
2. Send it to Gemini with a prompt asking for logical, atomic commit grouping (or group locally if --no-ai is used)
3. Print a proposed breakdown like:

────────────────────────────────────────────────────
Commit 1/2
────────────────────────────────────────────────────
  Message : fix: correct token refresh race condition
  Files   : src/auth/token.ts
  Why     : Refresh logic and retry handling are tightly coupled.

You can then decide whether the grouping is useful or too broad.

What this prototype does

• Groups messy diffs into logical commit units
• Uses Conventional Commits style messages such as feat:, fix:, chore:, refactor:, and style:
• Highlights when unrelated work seems bundled together
• Helps test whether AI-generated commit grouping feels genuinely helpful
• Offers multiple grouping strategies:
  • Default mode: reads full file contents for better context
  • Fast mode (--fast): uses diff hunks only, no file reads
  • Local mode (--no-ai): groups files by directory without any API call
  • Squash mode (--squash-merge): combines all changes into exactly one commit

Included demo repo

The repository includes a small fixture under test-repo/ with intentionally mixed changes. You can run the tool there to see how it behaves on a realistic but messy diff.

cd test-repo
node ../commitor.js

Notes

This is a prototype for research and feedback. The goal is to evaluate commit grouping quality, not to build a complete production release pipeline yet.