gai/README.md

gai

AI-powered Git helper — commit messages, PRs, code review, changelogs, and more

Generate Conventional Commits messages, pull request descriptions, code reviews, changelogs, and more — powered by AI with full project context.

---

Features

• 🤖 AI Commit Messages — generate Conventional Commits from staged diffs with project context
• 🔀 AI Pull Requests — create GitHub, Gitea, or GitLab PRs with AI-generated title and body
• 📖 Explain Changes — gai explain explains diffs in plain language
• 🔍 Code Review — gai review provides thorough, constructive code review
• 📝 Changelog Generation — gai changelog generates user-facing changelogs from commits
• 💡 Smart Suggestions — gai suggest recommends branch names or commit types
• ✏️ Amend Commits — gai commit --amend amends with AI-generated message
• ⚡ Streaming Output — AI responses stream token-by-token for instant feedback
• 📂 Interactive File Selection — ↑/↓ navigate, space toggle, "Select all" support
• 📋 Pipe Support — pipe diffs directly: git diff | gai explain
• 🎨 Mainstream CLI UX — proper flags, aliases, --help per command, --no-color
• 🔧 OpenAI-compatible API — works with DeepSeek, OpenAI, Ollama, OpenRouter, and more

Quick Start

# Install dependencies
bun install

# Configure your API key
gai config

# Open interactive menu
gai

# Generate a commit message
gai commit

# Explain your changes
gai explain

Usage

gai                       Open interactive menu
gai commit                Generate AI commit message (interactive file selection)
gai commit -a             Auto-stage all changed files
gai commit -d             Generate message without committing
gai commit -m "msg"       Use custom message (skip AI)
gai commit --amend        Amend last commit with AI-generated message
gai pr                    Create a PR with AI-generated title and body
gai pr --draft            Create a draft PR
gai explain               Explain staged changes in plain language
gai explain --unstaged    Explain unstaged changes
gai review                AI code review of staged changes
gai review --strict       Thorough review, flag minor issues
gai review --lenient      Focus only on major issues
gai changelog             Generate changelog from recent commits
gai changelog --from v1.0 --to v1.1   Range-based changelog
gai suggest branch        Suggest branch names for current changes
gai suggest type          Suggest Conventional Commit type
gai config                Configure API settings (interactive)
gai config list           List all settings
gai config get <key>      Get a specific setting
gai config set <key> <v>  Set a setting
gai help                  Show help
gai help <command>        Show command-specific help
gai --version             Show version

Global Flags

Flag	Description
-h, --help	Show help
-V, --version	Show version
-v, --verbose	Verbose output
--no-color	Disable colored output

Also respects the NO_COLOR and FORCE_COLOR environment variables.

Subcommand Aliases

Command	Aliases
commit	c, ci
pr	p
config	cfg
explain	x
review	r, rv
changelog	cl, log
suggest	sg
help	h

Pipe Support

All AI commands accept piped input — no git repository required:

# Explain any diff
git diff main..feature | gai explain

# Review changes from a PR
curl https://patch-diff.githubusercontent.com/... | gai review

# Suggest branch name for a diff
git diff | gai suggest branch

Interactive Menu

Run gai without arguments to open the mole-style interactive menu:

  gai v0.1.3
  AI-powered git helper for commits, PRs, reviews, and changelogs
  ────────────────────────────────────────────────────────────────────────

  CREATE
  │ › 1  Commit     Generate AI commit message
      2  PR         Create a PR with AI-generated title
      3  Amend      Amend last commit with AI message

  INSPECT
      4  Explain    Explain staged changes in plain language
      5  Review     AI code review of staged changes
      6  Changelog  Generate changelog from commits
      7  Suggest    Suggest branch name or commit type

  PROJECT
      8  Config     Configure API settings

  ────────────────────────────────────────────────────────────────────────
  ↑/↓ navigate   enter run   1-8 jump   h help   v version   q quit

Number keys 1–8 jump directly to the corresponding action. After a command finishes, press Enter to return to the menu.

Command Examples

Commit

# Interactive file selection
gai commit

# Auto-stage everything
gai commit -a

# Dry-run (no commit)
gai commit -d

# Custom message (skip AI)
gai commit -m "fix: correct typo in README"

# Amend last commit with AI message
gai commit --amend

# Pipe diff for commit message
git diff --staged | gai commit

PR

# Create PR
gai pr

# Draft PR
gai pr --draft

Explain

# Explain staged changes
gai explain

# Explain unstaged changes
gai explain --unstaged

# Pipe any diff
git diff HEAD~3 | gai explain

Review

# Review staged changes (normal strictness)
gai review

# Thorough review
gai review --strict

# Lenient review
gai review --lenient

# Review unstaged changes
gai review --unstaged

Changelog

# From last 20 commits
gai changelog

# Custom count
gai changelog -n 50

# Between tags
gai changelog --from v1.0.0 --to v1.1.0

Suggest

# Suggest branch name
gai suggest branch

# Suggest commit type
gai suggest type

Configuration

Via gai config (interactive)

gai config

CLI-based config

gai config list
gai config get model
gai config set model gpt-4o
gai config set temperature 0.3

Via environment variables

Variable	Default	Description
GAI_API_KEY	—	Required. Your API key
GAI_API_BASE	https://api.deepseek.com/v1	API base URL
GAI_MODEL	deepseek-v4-flash	Model name
GAI_MAX_TOKENS	500	Max response tokens
GAI_TEMPERATURE	0.7	Sampling temperature

Via .env file

Bun auto-loads .env — no dotenv needed:

GAI_API_KEY=sk-your-key
GAI_API_BASE=https://api.deepseek.com/v1
GAI_MODEL=deepseek-v4-flash

Using other providers

OpenAI

GAI_API_KEY=sk-xxx
GAI_API_BASE=https://api.openai.com/v1
GAI_MODEL=gpt-4o

Ollama (local)

GAI_API_KEY=ollama
GAI_API_BASE=http://localhost:11434/v1
GAI_MODEL=llama3

OpenRouter

GAI_API_KEY=sk-or-xxx
GAI_API_BASE=https://openrouter.ai/api/v1
GAI_MODEL=anthropic/claude-sonnet-4

How It Works

┌─────────────────────────────────────────────┐
│                gai                           │
├─────────────────────────────────────────────┤
│  1. Collect project context                  │
│     ├─ README.md / package.json              │
│     └─ Directory structure                   │
│                                              │
│  2. Collect code changes                     │
│     ├─ git diff --staged for commits         │
│     ├─ Branch diff for pull requests         │
│     └─ Pipe support for external diffs       │
│                                              │
│  3. Collect commit history                   │
│     ├─ git log --oneline -10 for commits     │
│     └─ Branch commits for pull requests      │
│                                              │
│  4. Build prompt → Call AI API (streaming)   │
│                                              │
│  5. Review → Confirm → Commit or Create PR   │
└─────────────────────────────────────────────┘

Build

Compile to a standalone binary:

bun run build
# Output: ./gai

Test

bun test

License

MIT