gritch

AI-powered Git assistant (Groq-powered, free/no paid API required)

gritch is an AI-powered CLI that helps you write Conventional Commits, generate CHANGELOG.md entries, review staged diffs before you push, and explain commits in plain English. It solves the “blank commit message” problem and streamlines the review + documentation workflow using Groq.

Features

• AI-generated conventional commit messages
• Pre-push code review with scoring
• Automatic CHANGELOG.md generation
• Plain-English commit explanations
• Works in any git repo
• Free to use with Groq API

Installation

npm install -g gritch

Setup

1. Get a Groq API key from https://console.groq.com/.
2. Set the GROQ_API_KEY environment variable.

Windows PowerShell

$env:GROQ_API_KEY = "your_key_here"

macOS / Linux (bash/zsh)

export GROQ_API_KEY="your_key_here"

Permanent Setup (Recommended)

Setting the API key with export (macOS/Linux) or $env (Windows PowerShell) only lasts for the current terminal session. When you close the terminal, the environment variable is lost.

To make GROQ_API_KEY available in every new terminal session:

Windows

1. Open the Start Menu and search for Environment Variables.
2. Click Edit the system environment variables.
3. Click the Environment Variables button.
4. Under User variables, click New.
5. Set the variable name to GROQ_API_KEY.
6. Set the variable value to your Groq API key.
7. Click OK on all dialogs.
8. Restart the terminal.

macOS

1. Open Terminal.
2. Run:

   echo 'export GROQ_API_KEY="your_key_here"' >> ~/.zshrc

3. Then run:

   source ~/.zshrc

Linux

1. Open Terminal.
2. Run:

   echo 'export GROQ_API_KEY="your_key_here"' >> ~/.bashrc

3. Then run:

   source ~/.bashrc

After doing this, gritch will work in any terminal session without needing to set the key again.

Usage

Generate a Conventional Commit message from staged changes:

gritch commit

Review staged changes before pushing (default language: typescript):

gritch review

Review staged changes with a specific language:

gritch review --language javascript

Generate a CHANGELOG.md for a version range:

gritch changelog v1.0.0 v1.1.0

Explain what a commit did in plain English:

gritch explain abc123def456

{ "model": "llama-3.3-70b-versatile", "maxTokens": 1024, "reviewThreshold": 7, "conventionalCommits": true }

## Built With
- TypeScript
- Node.js
- Groq AI
- LLaMA 3.3
- Commander.js
- simple-git

## License
MIT

## Contributing
Contributions are welcome! Open an issue or submit a pull request—whether it’s bug fixes, new features, or documentation improvements.