349 lines
8.9 KiB
Markdown
349 lines
8.9 KiB
Markdown
<div align="center">
|
||
|
||
# gai
|
||
|
||
**AI-powered Git helper — commit messages, PRs, code review, changelogs, and more**
|
||
|
||
[](./LICENSE)
|
||
[](https://bun.sh)
|
||
[](https://www.typescriptlang.org/)
|
||
|
||
Generate **Conventional Commits** messages, pull request descriptions, code reviews, changelogs, and more — powered by AI with full project context.
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
## 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 <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:
|
||
|
||
```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
|
||
|
||
<details>
|
||
<summary><strong>OpenAI</strong></summary>
|
||
|
||
```bash
|
||
GAI_API_KEY=sk-xxx
|
||
GAI_API_BASE=https://api.openai.com/v1
|
||
GAI_MODEL=gpt-4o
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><strong>Ollama (local)</strong></summary>
|
||
|
||
```bash
|
||
GAI_API_KEY=ollama
|
||
GAI_API_BASE=http://localhost:11434/v1
|
||
GAI_MODEL=llama3
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><strong>OpenRouter</strong></summary>
|
||
|
||
```bash
|
||
GAI_API_KEY=sk-or-xxx
|
||
GAI_API_BASE=https://openrouter.ai/api/v1
|
||
GAI_MODEL=anthropic/claude-sonnet-4
|
||
```
|
||
|
||
</details>
|
||
|
||
## 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)
|