Human‑quality commit messages. Zero hassle.
AI‑assisted commit message generator with a delightful terminal UX and a one‑command Git hook. Works offline (heuristics) and gets even better with OpenAI.
- Polished commit messages for your staged changes
- Beautiful terminal UI (emoji‑friendly, powered by Rich)
- One‑liner Git hook to auto‑fill commit messages
- Works offline by default; seamlessly upgrades to OpenAI when available
- Simple config with sane defaults; interactive refine/edit session
Requires Python 3.8+.
- pipx (recommended, isolated CLI)
pipx install diffmind- pipx with OpenAI extras
pipx install "diffmind[ai]"- pip (core, offline)
pip install -U diffmind- pip with OpenAI extras
pip install -U "diffmind[ai]"Upgrade / uninstall:
- pipx upgrade
pipx upgrade diffmind- pip upgrade
pip install -U diffmind- pipx uninstall
pipx uninstall diffmind- pip uninstall
pip uninstall diffmindOption A — editable install (pip):
- Clone
git clone https://github.com/dirusanov/DiffMind.git- Enter directory
cd DiffMind- Install (editable) with OpenAI extras
pip install -e ".[ai]"- Or install (editable) core only
pip install -e .Option B — development setup (Poetry):
- Clone
git clone https://github.com/dirusanov/DiffMind.git- Enter directory
cd DiffMind- Install dependencies
poetry install- Verify CLI in venv
poetry run diffmind --help# One-time setup (detects OpenAI automatically if OPENAI_API_KEY is set)
diffmind init
# Suggest a message for staged changes
diffmind suggest
# Commit with the generated message (and stage all changes)
diffmind commit -a
# Interactive refinement session (arrows + free text)
diffmind sessionAdd the Git hook (if you skipped it during init):
diffmind hook install┌──────────────────────────── Commit Message Suggestion ────────────────────────────┐
│ ✨ feat: add login form and validation (auth) │
│ │
│ - app/auth/LoginForm.tsx: +182 -0 │
│ - app/auth/validators.ts: +64 -0 │
│ - i18n/en.json: +12 -0 │
└──────────────────────────────────────────────────────────────────────────────────┘
💡 Use `diffmind commit` to commit with this message.
Interactive actions:
✅ Commit 🔁 Regenerate ✏️ Edit subject/body 📝 Open in $EDITOR ➕ Add bullet
- simple (default) — Fast, offline heuristics based on your staged diff and file paths
- openai (optional) — OpenAI chat completion for highly polished messages
Enable OpenAI:
- Set API key
export OPENAI_API_KEY=sk-...- Install with extras (pip)
pip install -U "diffmind[ai]"- Or install provider only (pip)
pip install -U openaiOr run the guided setup:
diffmind config wizardDiffMind reads configuration from the first existing file:
.diffmind.toml(repo)~/.config/diffmind/config.toml(user)
Example .diffmind.toml:
provider = "auto" # auto | simple | openai
conventional = true # Conventional Commit types
emojis = true # emoji prefix in subject
max_subject_length = 72
scope_strategy = "topdir" # topdir | none
language = "auto" # auto | en | ru
# OpenAI (optional)
openai_model = "gpt-4o-mini"
# openai_base_url = "https://api.openai.com/v1"Environment overrides:
DIFFMIND_PROVIDERDIFFMIND_EMOJIS(1/0, true/false)DIFFMIND_CONVENTIONAL(1/0, true/false)OPENAI_API_KEY(for the OpenAI provider)
- Installs
prepare-commit-msgthat pre-fills an empty message using DiffMind - Respects existing messages (never overwrites non‑comment content)
Commands:
diffmind hook install
# ... later
diffmind hook uninstall- OpenAI not detected? Ensure the
openaipackage is installed andOPENAI_API_KEYis set. Rundiffmind doctor. - No staged changes? DiffMind only considers staged files.
git add -Afirst or usediffmind commit -a. - Prefer manual edits? Use
diffmind sessionand choose “Open in $EDITOR”.
- The simple provider never sends code anywhere and runs locally.
- The OpenAI provider sends only the staged diff and prompt context to your configured OpenAI endpoint.
- You control when OpenAI is used (auto/explicit) and can disable it any time.
Contributions are welcome! If you plan to add a provider or improve agent flows/prompts, please keep the UX consistent and simple. Open an issue to discuss ideas.
MIT