git-hermes

AI-powered git commit messages from your staged diffs. Easy, fast, and configurable.

Table of Contents

• Getting Started
• Usage
• Configuration
• AI Providers
• Contributing
• License

Getting Started

Homebrew (recommended)

brew install winzamark123/tap/git-hermes

npm / Bun

# npm
npm i -g git-hermes

# bun
bun i -g git-hermes

# one-shot with npx
npx git-hermes

[!TIP] git-hermes installs as a git subcommand — no aliases needed. Any binary named git-<name> is automatically available as git <name>.

On first run, a default config is created at ~/.config/hermes/config.json with OpenAI (gpt-4o) as the default provider. Set your API key by opening the config in your editor:

git hermes config
# add your API key: "apiKey": "sk-..."

Or pass it inline:

git hermes -p anthropic -m claude-sonnet-4-20250514 -k sk-ant-your-key

Usage

# generate a commit message and commit
git hermes

# guide the commit with your intention
git hermes "add user authentication"

# preview a guided message without committing
git hermes "fix login redirect bug" --dry-run

# preview the message without committing
git hermes --dry-run

# override provider and model
git hermes -p anthropic -m claude-sonnet-4-20250514

# pass an API key inline
git hermes -k sk-your-key

# custom system prompt for one run
git hermes --prompt "be concise, no scope"

# open config in $EDITOR
git hermes config

# show help
git hermes --help

Intentional Commits

Pass a quoted string to guide the subject line of the generated commit message:

[!TIP] You should always commit intentionally! Know what code you are pushing.

git hermes "add user authentication"
# → feat(auth): add user authentication
#
# - add login endpoint with JWT token generation
# - create user model with password hashing
# - add auth middleware for protected routes

git hermes "fix login redirect bug"
# → fix(auth): fix login redirect bug
#
# - correct redirect URL after successful login
# - handle edge case for expired sessions

The AI still determines the appropriate type and scope from your diff — your intention replaces only the short description. Without an intention, hermes generates the entire message automatically.

[!IMPORTANT] By default, git-hermes generates commit messages following the Conventional Commits specification. You can override this with a custom prompt via --prompt or your config file.

Configuration

Config file: ~/.config/hermes/config.json

{
  "provider": "openai",
  "model": "gpt-4o",
  "apiKey": "sk-...",
  "prompt": "optional custom system prompt",
  "animationColor": "cyan"
}

Priority

Values are resolved in this order (highest wins):

| Source | Scope | Provider | Model | API Key | |---|---|---|---|---| | CLI flag | Single run | -p, --provider | -m, --model | -k, --api-key | | Environment variable | Shell session | HERMES_PROVIDER | HERMES_MODEL | HERMES_API_KEY | | Config file | Persistent | provider | model | apiKey | | Default | — | openai | gpt-4o | — |

For persistent settings, edit your config with git hermes config. CLI flags and environment variables are temporary and do not modify the config file.

Animation Color

Customize the spinner and karaoke text color during commit message generation:

{
  "animationColor": "magenta"
}

Supported colors: black, red, green, yellow, blue, magenta, cyan (default), white, gray.

Custom Prompts

Override the default system prompt to change commit message style:

# one-off override
git hermes --prompt "use gitmoji format"

# persistent override via config
git hermes config
# then add "prompt": "your custom prompt"

AI Providers

git-hermes uses the Vercel AI SDK and supports any model from these providers:

| Provider | Flag | Example models | Supported models | |---|---|---|---| | OpenAI | -p openai | gpt-4o, gpt-4o-mini, o3-mini | View all | | Anthropic | -p anthropic | claude-sonnet-4-20250514, claude-haiku-4-5-20251001 | View all | | Google | -p google | gemini-2.0-flash, gemini-2.5-pro | View all | | Groq | -p groq | llama-3.3-70b-versatile | View all |

Contributing

Interested in contributing? We'd love your help.

1. Fork the repo
2. Create your branch (git checkout -b my-feature)
3. Make your changes
4. Run typechecks (bun run tsc --noEmit)
5. Commit and push
6. Open a pull request

License

MIT