minimaldiff

minimaldiff (alias: mdiff) is a CLI that reads your local git changes, groups related files into commit-sized chunks, drafts strong commit subjects with Gemini, and only commits after you approve each one. It never runs git push.

Requirements

• Node.js 20+
• git on your PATH
• A Gemini API key (create one at https://aistudio.google.com/apikey)

Install

npm install -g minimaldiff

Or run without installing:

npx -p minimaldiff minimaldiff
npx -p minimaldiff mdiff

Quickstart

Run inside any git repo:

minimaldiff

You’ll see proposed commits one-by-one:

• press Enter to commit
• type e to edit the message
• type s to skip that group
• type q to stop

API key + config

On first run, if no key is configured, the CLI prompts you for a Gemini API key and stores it locally.

• env vars (skip prompts): GEMINI_API_KEY or MINIMALDIFF_GEMINI_API_KEY
• config location: ~/.minimaldiff/config.json when possible; otherwise ./.minimaldiff/config.json

Flags

| Flag | Alias | Description | | --- | --- | --- | | --help | -h | Show help (same as minimaldiff help) | | --about | | What the tool does + version + install footprint | | --status | | Show recent commits created via minimaldiff in this repo | | --staged | | Commit only staged files (safe mode when you’ve already staged) | | --key [add\|remove] | | Manage saved Gemini API key (add/set, remove/rm/clear) |

Commands

| Command | Description | | --- | --- | | minimaldiff | Run the workflow on unstaged + untracked changes | | minimaldiff run | Same as above | | minimaldiff staged | Run the workflow on staged changes only | | minimaldiff doctor | Check git + local config path | | minimaldiff status | Same as --status | | minimaldiff reset-key | Clear saved key (same as --key remove) | | minimaldiff help | Same as --help |

All commands also work with the mdiff alias (for example mdiff doctor).

Safety notes

• If you have staged changes, minimaldiff won’t touch them. Use minimaldiff --staged (or minimaldiff staged) to commit only what’s staged.
• Commits are created on your current branch only. Nothing is pushed.

Examples

Commit your current unstaged work:

mdiff

Commit only what you staged yourself:

mdiff --staged

Save/remove the Gemini API key:

mdiff --key add
mdiff --key remove

Check setup:

mdiff doctor

Develop from source

npm install
npm run build
npm run cli

License

MIT — see LICENSE.