gut 🫀

Trust your guts on git — An AI-powered CLI tool that executes git and gh commands from natural language queries.

Transform commands like "add all my changes and commit with a meaningful message" into the exact git commands you need, with AI-powered intelligence and human-in-the-loop validation.

✨ Features

• 🤖 Natural Language Processing: Describe what you want to do in plain English
• 🔄 Human-in-the-Loop: Review and approve commands before execution
• 🎯 Smart Command Selection: Automatically chooses between git and gh commands
• 📖 Command Explanation: Get clear explanations of what each command does
• 🎨 Rich Console Interface: Beautiful terminal experience with syntax highlighting

🚀 Quick Start

Installation

Install gut using pip:

pip install gut-ai

Setup

1. Get a Groq API key
2. Set your API key as an environment variable:

export GROQ_API_KEY="your_api_key_here"

Or create a .env file in your project directory:

GROQ_API_KEY=your_api_key_here

Usage

Simply run gut and describe what you want to do:

gut-ai

Example interactions:

• "Add all my current changes to git"
• "Create a new branch called feature/login"
• "Push my changes to origin"
• "Create a pull request"

You can also run gut to check and correct your commands:

gut-ai --command "git commit 'feat: analytics'" --question "Why is my command failing?"

Or to simply explain them:

gut-ai --command "git checkout -b 'feat/analytics'"

Note: You can also use the -c and -q as abbreviated flags.

🔧 Development Setup

Prerequisites

• uv package manager

Clone and Install

git clone https://github.com/AstraBert/gut
cd gut/
uv sync

Run from Source

uvx --from . gut-ai

🛠️ How It Works

gut uses an AI-powered workflow built with llama-index-workflows that follows these steps:

Gut interface

1. Command Analysis: Analyzes your natural language input to understand intent
2. Command Selection: Chooses between git and gh based on your requirements
3. Parameter Mapping: Determines the specific subcommands and options needed
4. Explanation Generation: Creates a clear explanation of what the command will do
5. Human Validation: Shows you the command and explanation for approval
6. Execution: Runs the command if approved, or restarts the process with your feedback

Gut --command and --question

1. Command Analysis: Analyzes your command and question, producing an explanation and a potential fix for it.
2. Human Validation: Shows you the explanation and, if there, the corrected command and waits for approval
3. Execution: Runs the command if approved, or restarts the process with your feedback

The entire experience runs in a beautiful Rich console interface with structured inputs and outputs using Pydantic models.

📋 Requirements

• Groq API Key: Required for AI functionality
• Git: Must be installed and configured
• GitHub CLI (optional): Required only for GitHub-related commands (gh)

🤝 Contributing

We welcome contributions! Please read our Contributing Guide to get started.

📄 License

This project is licensed under the MIT License.

🙋‍♀️ Support

• 🐛 Bug Reports: Open an issue
• 💡 Feature Requests: Start a discussion
• 📧 Questions: Check existing issues and discussions

---

Made with ❤️ for developers who want to git things done faster