zeus-ai is a Git-aware CLI tool that helps developers generate smart commit messages using LLM APIs. It analyzes your Git diff, sends it to an LLM (such as DeepSeek, Claude, or any local model via Ollama), receives multiple commit message suggestions, and allows you to select and edit the message before committing.

Full Demo Video

• Multiple LLM Provider Support: Ollama, OpenRouter
• Git Integration: Works with staged/unstaged changes, supports signed commits
• Smart Suggestions: Generate multiple commit message options based on your changes
• Flexible Configuration: Config file, environment variables, command flags
• Terminal UI: Simple interface for selecting and editing commit messages

# Clone the repository
git clone https://github.com/amosehiguese/zeus-ai.git

# Navigate to the directory
cd zeus-ai

# Build the binary
go build -o zeusctl ./zeusctl or make build

# Move to path (optional)
sudo mv zeusctl /usr/local/bin/

Download the binary for your platform from the releases page.

Initialize a configuration file with guided setup:

zeus-ai init

This will create a .zeusrc file in the current directory with default settings.

zeus-ai looks for a .zeusrc file in the following locations, in order:

1. Current directory
2. Any parent directory (up to the root)
3. Home directory (~/.zeusrc)

Example .zeusrc file:

# LLM Provider configuration
provider: openrouter        
api_key: your-api-key-here
model: mistralai/mistral-small-3.1-24b-instruct:free

# Default commit style
default_style: conventional  # Options: conventional, simple

# Optional settings
editor: vim            # Overrides $EDITOR environment variable
sign_by_default: true  # Always sign commits
auto_stage: false      # Don't automatically stage all changes

All settings can be configured with environment variables, which take precedence over the config file:

# Required settings
export ZEUS_PROVIDER=openrouter
export ZEUS_API_KEY=your-api-key-here
export ZEUS_MODEL=mistralai/mistral-small-3.1-24b-instruct:free

# Optional settings
export ZEUS_DEFAULT_STYLE=conventional
export ZEUS_EDITOR=vim
export ZEUS_SIGN_BY_DEFAULT=true
export ZEUS_AUTO_STAGE=false

provider: ollama
model: mistral  # or any model you have pulled in Ollama
# No API key needed for local Ollama

provider: openrouter
api_key: your-openrouter-api-key
model: mistralai/mistral-small-3.1-24b-instruct:free  # or any other model supported by OpenRouter

zeus-ai suggest

This will:

1. Check for staged changes or ask to use unstaged changes
2. Send the diff to the configured LLM
3. Generate commit message suggestions
4. Display them for you to choose or edit
5. Create the commit with your selected message

# Include detailed body text in suggestions
zeus-ai suggest --body

# Open the selected message in default editor
zeus-ai suggest --edit

# GPG-sign the commit message once you've approved the commit message
zeus-ai suggest --sign

# Display message suggestions but don't run commit
zeus-ai suggest --dry-run

# Automatically stage all changes
zeus-ai suggest --auto-stage

# Specify commit style (conventional or simple)
zeus-ai suggest --style conventional

When using --style conventional, suggestions will follow the format:

type(scope): description

Where:

• type is one of: feat, fix, docs, style, refactor, test, chore
• scope is optional and specifies the section of the codebase
• description is a concise explanation of the change

zeus-ai suggest

zeus-ai suggest --body --style conventional --edit

zeus-ai suggest --dry-run

zeus-ai suggest --auto-stage --sign

1. Check Git Status: zeus-ai verifies you're in a Git repository and checks for staged changes
2. Collect Diff: Gets the Git diff of staged changes (or unstaged if specified)
3. Generate Suggestions: Sends the diff to the LLM to generate commit message suggestions
4. Present Options: Shows the suggestions with a simple selection interface
5. Edit (Optional): Opens your selected message in an editor if --edit is used
6. Commit: Creates the Git commit with your chosen message

Add zeus-ai to your Git workflow by setting up a Git alias:

git config --global alias.ai 'zeus-ai suggest'

Then use:

git ai

Error: failed to generate suggestions: API returned error: {"error":{"type":"auth_error"}}

Solution: Check your API key is correct in the config file or environment variable.

Error: failed to generate suggestions: Ollama server not running at http://localhost:11434

Solution: Start Ollama with ollama serve before using zeus-ai.

Error: no changes to commit

Solution: Make sure you have changes in your working directory and stage them with git add.

Contributions are welcome! See CONTRIBUTING.md for details.

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

• Cobra for CLI functionality
• Viper for configuration management
• OpenRouter, and Ollama for LLM APIs