iamngoni/gitwhisper

Generated by the Very Good CLI 🤖

---

Git Whisper is an AI-powered Git commit message generator that whispers the perfect commit message based on your staged changes.

---

Be nice and buy me a coffee alright or matcha 🤣

---

Editor Integrations 🔌

GitWhisper is also available as plugins for popular editors:

Visual Studio Code

Install the GitWhisper extension directly from the marketplace:

• Extension: GitWhisper for VS Code
• Developer: Panashe Mushinyi
• Features: Generate commit messages directly within VS Code's Git interface

JetBrains IDEs

Available for all JetBrains IDEs (IntelliJ IDEA, WebStorm, PhpStorm, etc.):

• Plugin: GitWhisper for JetBrains
• Developer: Panashe Mushinyi
• Features: Seamless integration with JetBrains VCS tools

Getting Started 🚀

If you have Dart installed, you can activate globally via:

dart pub global activate gitwhisper

Or locally via:

dart pub global activate --source=path <path to this package>

Or using Homebrew on Apple Silicon Macs or Linux:

brew tap iamngoni/homebrew-gitwhisper
brew install gitwhisper

There is no prebuilt binary for Intel Macs; use dart pub global activate gitwhisper there.

Or on Debian/Ubuntu using APT (supports amd64 and arm64):

echo "deb [trusted=yes] https://iamngoni.github.io/gitwhisper-apt stable main" | sudo tee /etc/apt/sources.list.d/gitwhisper.list
sudo apt update
sudo apt install gitwhisper

Or directly with curl:

curl -sSL https://raw.githubusercontent.com/iamngoni/gitwhisper/master/install.sh | bash

Or on the beloved Windows using Powershell (as Administrator):

irm https://raw.githubusercontent.com/iamngoni/gitwhisper/master/install.ps1 | iex

Or download the executable binary that will work on your operating system directly here.

Features

• 🤖 Leverages various AI models to analyze your code changes and generate meaningful commit messages
• 🔄 Follows conventional commit format: <type>: <description> or <type>: <emoji> <description> when emojis are enabled
• ✨ Interactive commit confirmation - Review, edit, retry with different models, or discard generated messages
• 📋 Pre-fills the Git commit editor for easy review and modification
• 🚀️ Supports automatic pushing of commits to the remote repository
• 🔍 Code analysis to understand staged changes and get suggestions for improvements
• 🎫 Supports ticket number prefixing for commit messages
• 🏷️ Create git tags alongside commits with optional auto-push
• 🧩 Choose specific model variants (gpt-5.6-terra, claude-sonnet-5-5, etc.)
• 🔑 Securely saves API keys for future use
• 🌍 Multi-language support for commit messages and analysis
• 🧪 --dry-run to preview the generated message without creating a commit
• 🧠 Agent mode is used by default for providers that support tools
• 🛠️ Local ACP agents can inspect staged changes through GitWhisper's read-only MCP tools, with live tool activity shown while they work
• 🔌 Supports multiple AI models:
  • Claude (Anthropic)
  • Claude Code local auth
  • Codex local auth
  • OpenAI (GPT)
  • Gemini (Google)
  • Grok (xAI)
  • Meta Model API (llama)
  • Deepseek (DeepSeek, Inc.)
  • All Ollama models

Usage

# Generate a commit message (main command)
gitwhisper commit --model openai
gitwhisper # shorthand for 'gitwhisper commit' - runs commit command by default
gw # even shorter command - also runs 'gitwhisper commit' by default

# Choose a specific model variant
gitwhisper commit --model openai --model-variant gpt-5.6-terra
gw commit --model openai --model-variant gpt-5.6-terra

# Tool-capable models use agent mode by default
gitwhisper commit --model openai
gitwhisper commit --model claude
gitwhisper commit --model gemini
gitwhisper commit --model grok
gitwhisper commit --model llama
gitwhisper commit --model deepseek
gitwhisper commit --model ollama

# Add a ticket number prefix to your commit message
gitwhisper commit --prefix "JIRA-123"
gw commit --prefix "JIRA-123"

# Automatically push the commit to the branch's upstream
# (with no upstream and a single remote, it is pushed with -u)
gitwhisper commit --auto-push
gw commit --auto-push
gw commit -a # shorthand for --auto-push

# Create a git tag for this commit
gitwhisper commit --tag v1.0.0
gw commit -t v1.0.0

# Combine tag with auto-push to push both commit and tag
gw commit -t v1.0.0 -a

# Preview the generated message without committing (no commit, push, or tag)
gitwhisper commit --dry-run
gw commit --dry-run

# Send the staged diff in the prompt instead of letting the model inspect it with tools
gw commit --no-agent

# Use local-auth agent providers (no GitWhisper API key required)
gitwhisper commit --model codex
gitwhisper commit --model claude-code

# Use local ACP agent providers from the registry
gitwhisper commit --model qoder
gitwhisper commit --model poolside

# Analyze your changes (staged/unstaged) with AI
gitwhisper analyze
gw analyze

# List available models
gitwhisper list-models
gw list-models

# List available variants for a specific model
gitwhisper list-variants --model claude
gw list-variants --model claude

# Work with ACP agents from the registry
gitwhisper acp list
gw acp list
gw acp list --all        # include entries not used for commits
gw acp info qoder
gw acp resolve codex
gw acp install poolside
gw acp trust .   # allow ACP agents in a repo that ships agent config (see below)
gw acp untrust .
gw acp cache path
gw acp cache refresh

# Change the language for commit messages and analysis
gitwhisper change-language
gw change-language

# Save an API key for future use (prompts for the key without echoing it)
gitwhisper save-key --model claude
gw save-key --model claude

# Set defaults (model is required, model-variant is optional)
gitwhisper set-defaults --model openai --model-variant gpt-5.6-terra
gw set-defaults --model openai --model-variant gpt-5.6-terra

# Set just the default model (without variant)
gitwhisper set-defaults --model claude
gw set-defaults --model claude

# Set defaults for Ollama with custom base URL
gitwhisper set-defaults --model ollama --model-variant llama3 --base-url http://localhost:11434
gw set-defaults --model ollama --model-variant llama3 --base-url http://localhost:11434

# Set the largest diff (characters) that `--no-agent` sends in one prompt;
# larger diffs are summarised file by file
gw set-defaults --max-diff-size 100000

# Show current defaults
gitwhisper show-defaults
gw show-defaults

# Clear defaults
gitwhisper clear-defaults
gw clear-defaults

# Always stage changes first
gitwhisper always-add true
gw always-add true

# Get help
gitwhisper --help
gw --help

Shorter Command

Instead of using the full gitwhisper command you can also use the shortened one gw. Both gitwhisper and gw without any subcommands will automatically run the commit command by default.

Interactive Commit Confirmation

GitWhisper now features an interactive commit confirmation workflow that gives you full control over your commit messages:

What You Can Do:

• Apply: Use the generated commit message as-is
• Edit: Modify the commit message before applying
• Retry: Generate a new message with the same model
• Try Different Model: Generate with a different AI model
• Discard: Cancel and exit without committing

Example Workflow:

$ gitwhisper commit
🔮 Analyzing your changes...
✨ Generated commit message: feat: Add user authentication system

Options:
[A] Apply commit message
[E] Edit commit message
[R] Retry with same model
[M] Try different model
[D] Discard and exit

What would you like to do? (A/e/r/m/d):

Command Structure

GitWhisper uses a command-based structure:

• commit: Generate and apply a commit message with interactive confirmation (main command)
• analyze: Examine changes (staged/unstaged) and provide detailed code analysis with suggestions for improvements
• list-models: Show all supported AI models
• list-variants: Show available variants for each AI model
• acp: Inspect, resolve, install, and cache ACP registry agents
• change-language: Set the language for AI-generated commit messages and analysis
• save-key: Store an API key for future use
• update: Update GitWhisper to the latest version
• set-defaults: Set default model and variant for future use (supports --base-url for Ollama)
• show-defaults: Display current default settings
• show-config: Display the current config file path and contents (API keys are masked; pass --reveal to show them)
• clear-defaults: Clear any set default preferences
• always-add: Configure whether GitWhisper stages changes before committing

API Keys

You can provide API keys in several ways:

1. Saved configuration (recommended): run gw save-key --model <model> and paste the key at the hidden prompt. The config file is written with owner-only (0600) permissions.
2. Environment variables:
   • ANTHROPIC_API_KEY (for Claude)
   • OPENAI_API_KEY (for OpenAI)
   • GEMINI_API_KEY (for Gemini)
   • GROK_API_KEY (for Grok)
   • LLAMA_API_KEY (for the Meta Model API)
   • DEEPSEEK_API_KEY (for DeepSeek)
3. Command line argument: --key "your-api-key". This still works but prints a warning, because the key ends up in your shell history and process list.

Local-auth agent providers and ACP agents do not need GitWhisper API keys:

• codex reads the same local Codex credentials used by the Codex CLI, calls the Codex Responses API directly, and lets that model inspect staged changes through GitWhisper's read-only tools.
• claude-code reads Claude Code local credentials from environment, ~/.claude, or the macOS keychain, calls Anthropic Messages directly, and lets that model inspect staged changes through GitWhisper's read-only tools. An apiKeyHelper in a repository's .claude/settings.json or .claude/settings.local.json is only used after you have trusted that folder in Claude Code; otherwise only your user and managed settings are read.
• When codex or claude-code refreshes an expired login, the refreshed tokens are written back atomically with owner-only permissions, and tokens the CLI itself refreshed in the meantime are kept rather than overwritten.
• Other supported ACP agent ids can be used directly, for example qoder, poolside, cline, or other agents shown by gw acp list.

GitWhisper caches the ACP registry under ~/.gitwhisper/acp/registry.json. The cache is used first when it is fresh (refreshed at most every 6 hours), so commits stay off the network on the hot path; a stale or missing cache triggers a background fetch. If the registry cannot be fetched, GitWhisper falls back to the cached copy. If there is no cache yet, it prints a clear registry/cache error with a link to file a support issue. Run gw acp cache refresh to force an immediate network refresh. Binary-only ACP agents are installed under ~/.gitwhisper/acp/agents/ when you run gw acp install <agent> or when GitWhisper needs to launch them. Binary downloads must use HTTPS and are checked against the registry's sha256 checksum when the registry publishes one.

Agents are matched by their exact registry id (or a known alias); a near miss prints "did you mean" suggestions instead of guessing. The first time a given agent version is launched, GitWhisper shows exactly what will run (npm package or download URL, command, and environment) and asks before starting it. Run gw acp install <agent> to approve it ahead of time, for example for git hooks or CI; non-interactive runs refuse to launch an agent that was never approved.

ACP agents start in a private GitWhisper directory rather than in your repository, so a repository's .npmrc or node_modules cannot change what runs. The agent still works on your repository through the ACP session. If the repository ships agent configuration that can run commands (for example .claude/, .mcp.json, .gemini/, .codex/, .cursor/, .npmrc or node_modules/), GitWhisper lists it and asks before an ACP agent works there, once per repository. Without a terminal (CI, git hooks) it refuses until you run gw acp trust <path>; gw acp untrust <path> revokes it.

While an agent runs, GitWhisper auto-approves only its own read-only git tools, one call at a time. Every other permission request (shell commands, file edits, web fetches) is rejected. Unsupported or generic registry entries are hidden from the default commit-agent list. Use gw acp list --all to see every registry entry; entries GitWhisper does not target for commit generation are marked "not used for commits".

Which agents are supported. GitWhisper drives only first-party, product-backed coding agents — ones that ship as a branded product with their own authentication and a managed model (Codex, Claude Code, Gemini CLI, Cursor, GitHub Copilot, and similar). Their commit output is predictable and supported. The supported set is whatever the live registry publishes minus the exclusions below, so it grows as the registry does; run gw acp list for the current list.

What is excluded, and why. The following registry ids are not targeted for commit generation because they are not product-backed coding agents:

• Marketplaces / pay-per-call brokers: agoragentic-acp.
• Agent frameworks or SDKs (build-your-own-agent, not a product): deepagents, fast-agent.
• Generic, open-source, or bring-your-own-provider coding agents and ACP adapters, whose model and output quality vary by user setup: corust-agent, crow-cli, glm-acp-agent, goose, minion-code, opencode, pi-acp, sigit, vtcode.

This list lives in code (unsupportedCommitAgentIds) and may change over time; gw acp list --all is always the source of truth. If an agent you want is excluded, open an issue and we can evaluate adding it. While a local ACP agent works, GitWhisper shows its tool activity live (which files it reads, diffs, searches, and blames) instead of a silent wait. Set GITWHISPER_ACP_DEBUG=1 to write a debug log under ~/.gitwhisper/acp/logs/. Debug logs are off by default, record only message shapes (methods, ids, sizes, statuses — never prompts, diffs, or tool output), are readable only by you, and are deleted after 7 days.

Agent mode is enabled by default for tool-capable providers:

• gw commit --model openai
• gw commit --model claude
• gw commit --model gemini
• gw commit --model grok
• gw commit --model llama
• gw commit --model deepseek
• gw commit --model ollama
• gw commit --model codex
• gw commit --model claude-code
• gw commit --model <supported-acp-agent-id>

In agent mode, GitWhisper gives the model read-only tools for staged files, diff stats, per-file diffs, diff hunks, file-content chunks, file search, related files, summaries, and blame. The tools read staged content from the git index, so unstaged edits are never shown and staged symlinks are not followed. Direct API-backed providers receive these through native tool/function-calling APIs; local ACP agents receive them through GitWhisper's MCP server. The full diff is not sent in one prompt.

If an API model rejects tool use (for example an Ollama model without tool support), GitWhisper retries once in direct-diff mode, which sends the staged diff in the prompt. Pass --no-agent to use direct-diff mode from the start; diffs larger than max_diff_size are summarised file by file first.

If you cancel or discard a commit at any prompt, gw commit exits with code 75, so gw commit && git push does not push.

Model Variants

GitWhisper supports a comprehensive range of model variants:

OpenAI

• gpt-5.6-terra (default)
• gpt-5.6-sol
• gpt-5.6-luna
• gpt-5.5
• gpt-6-astra
• gpt-6.1-sol (no agent mode: no tool calls on Chat Completions)
• gpt-6-luna (no agent mode: tool calls need reasoning effort none)

Claude (Anthropic)

• claude-sonnet-5-5 (default)
• claude-opus-5-5
• claude-fable-5-1 (demanding reasoning)
• claude-haiku-5-5 (fastest)
• claude-opus-4-8
• claude-sonnet-4-6

Local-Auth Agent Providers

These providers call the model APIs directly while reusing local CLI credentials:

• codex uses the model in ~/.codex/config.toml when configured, otherwise gpt-5.5. Override with --model-variant.
• claude-code uses claude-sonnet-5-5 by default. Override with --model-variant.

Local ACP Agent Providers

• Supported ACP agent ids from gw acp list use that agent's own model/configuration.

Gemini (Google)

• gemini-3.6-flash (default)
• gemini-3.8-flash
• gemini-4-argon (most capable)
• gemini-3.5-flash-lite
• gemini-3.1-flash-lite
• gemini-2.5-pro (only for accounts that already used it)
• gemini-2.5-flash (only for accounts that already used it)

Grok (xAI)

• grok-4.3 (default)
• grok-4.7 (most capable)
• grok-4.6
• grok-4.5
• grok-4.20-0309-reasoning
• grok-4.20-0309-non-reasoning
• grok-build-0.1 (agentic coding)

Meta Model API (llama)

The llama provider uses Meta's OpenAI-compatible Meta Model API (https://api.meta.ai/v1) and needs a Meta Model API key.

• muse-spark-1.3 (default)
• muse-spark-1.2
• muse-spark-1.1

Deepseek (DeepSeek, Inc.)

• deepseek-flash (default)
• deepseek-v4-pro

GitHub Models (retired)

GitHub retired GitHub Models on July 30, 2026. --model github now stops with a message saying so instead of sending a request. Pick another provider.

Ollama (self-hosted)

• Check Ollama models here: https://ollama.com/search

How It Works

Git Whisper:

1. Checks if you have staged changes in your repository
2. Uses agent mode by default, or direct-diff mode with --no-agent or when the model rejects tools
3. In agent mode, exposes read-only staged-change tools instead of sending the whole diff at once
4. In direct-diff mode, retrieves the diff and sends it to the selected AI model
5. Generates a commit message following the configured conventional commit format
6. Shows you an interactive confirmation when confirmation is enabled - review, edit, retry, or discard the message
7. Applies any prefix/ticket number if specified
8. Submits the commit with the confirmed message

Language Support

GitWhisper supports generating commit messages and analysis in multiple languages:

• English (default)
• Spanish
• French
• German
• Chinese (Simplified & Traditional)
• Japanese
• Korean
• Arabic
• Italian
• Portuguese
• Russian
• Dutch
• Swedish
• Norwegian
• Danish
• Finnish
• Greek
• Turkish
• Hindi
• Shona
• Zulu

Language Behavior

When using non-English languages:

• Commit messages: The commit type (e.g., feat:, fix:) remains in English for tool compatibility. If emojis are enabled, the emoji also remains standard, while the description is generated in your selected language
• Analysis: The entire analysis response is provided in your selected language

Example commit message in Spanish:

feat: ✨ Agregar funcionalidad de modo oscuro

Use the change-language command to set your preferred language:

gitwhisper change-language
gw change-language

Configuration

Configuration is stored in ~/.git_whisper.yaml and typically contains your saved API keys and language preference:

api_keys:
  claude: "your-claude-key"
  openai: "your-openai-key"
  # ...
whisper_language: english
max_diff_size: 50000 # Largest diff --no-agent sends in one prompt before summarising file by file

Requirements

• Dart SDK (^3.5.0)
• Git installed and available in your PATH

Conventional Commit Format

Git Whisper generates commit messages following the conventional commit format:

fix: Fix login validation

When emojis are enabled, the emoji is placed after the type:

fix: 🐛 Fix login validation

With Prefix

If a prefix (e.g., a ticket number or task ID) is provided, Git Whisper intelligently formats it based on the number of commit messages:

• For a single commit message, the prefix is added before the description:

fix: PREFIX-123 -> Fix login validation

With emojis enabled:

fix: 🐛 PREFIX-123 -> Fix login validation

• For multiple unrelated commit messages, the prefix appears at the top, and each message remains a valid conventional commit:

PREFIX-123
feat: ✨ Add dark mode toggle
fix: 🐛 Resolve token refresh bug

This ensures your commits are always clean, readable, and traceable.

Common Commit Types and Emojis

Type	Emoji	Description
feat	✨	New feature
fix	🐛	Bug fix
docs	📚	Documentation changes
style	💄	Code style changes (formatting, whitespace, etc.)
refactor	♻️	Code refactoring (no new features or fixes)
test	🧪	Adding or updating tests
chore	🔧	Build process or auxiliary tool changes
perf	⚡	Performance improvements
ci	👷	Continuous Integration/Deployment changes
build	📦	Build system or dependency changes
revert	⏪	Revert a previous commit

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

---