git-hermes

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

commit.mp4

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