# gai **AI-powered Git helper — commit messages, PRs, code review, changelogs, and more** [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE) [![Bun](https://img.shields.io/badge/runtime-Bun-f9d71c.svg)](https://bun.sh) [![TypeScript](https://img.shields.io/badge/lang-TypeScript-3178c6.svg)](https://www.typescriptlang.org/) 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 ```bash # 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 Get a specific setting gai config set Set a setting gai help Show help gai help 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: ```bash # 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 ```bash # 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 ```bash # Create PR gai pr # Draft PR gai pr --draft ``` #### Explain ```bash # Explain staged changes gai explain # Explain unstaged changes gai explain --unstaged # Pipe any diff git diff HEAD~3 | gai explain ``` #### Review ```bash # Review staged changes (normal strictness) gai review # Thorough review gai review --strict # Lenient review gai review --lenient # Review unstaged changes gai review --unstaged ``` #### Changelog ```bash # 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 ```bash # Suggest branch name gai suggest branch # Suggest commit type gai suggest type ``` ## Configuration ### Via `gai config` (interactive) ```bash gai config ``` ### CLI-based config ```bash 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: ```bash GAI_API_KEY=sk-your-key GAI_API_BASE=https://api.deepseek.com/v1 GAI_MODEL=deepseek-v4-flash ``` ### Using other providers
OpenAI ```bash GAI_API_KEY=sk-xxx GAI_API_BASE=https://api.openai.com/v1 GAI_MODEL=gpt-4o ```
Ollama (local) ```bash GAI_API_KEY=ollama GAI_API_BASE=http://localhost:11434/v1 GAI_MODEL=llama3 ```
OpenRouter ```bash 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: ```bash bun run build # Output: ./gai ``` ## Test ```bash bun test ``` ## License [MIT](./LICENSE)