Mplan/gai
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

docs: update README and package.json for v0.2.0

Browse Source 
- Full README rewrite with all new commands, pipe support, aliases,
  global flags, and configuration examples
- Bump version to 0.2.0, update description
This commit is contained in:
Mplan
2026-06-16 02:01:07 +08:00
parent 4b384a7581
commit 4572605f33
2 changed files with 183 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+173 -60
View File
@@ -2,14 +2,13 @@
# gai # gai
**AI-powered Git commit and pull request helper** **AI-powered Git helper — commit messages, PRs, code review, changelogs, and more**
[![Release](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fgit.catpl.top%2Fapi%2Fv1%2Frepos%2FMplan%2Fgai%2Freleases%2Flatest&query=%24.tag_name&label=release&color=blue)](https://git.catpl.top/Mplan/gai/releases)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE) [![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) [![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/) [![TypeScript](https://img.shields.io/badge/lang-TypeScript-3178c6.svg)](https://www.typescriptlang.org/)
Generate **Conventional Commits** messages and pull request descriptions using AI, based on your project context, code diff, branch changes, and commit history. Generate **Conventional Commits** messages, pull request descriptions, code reviews, changelogs, and more — powered by AI with full project context.
</div> </div>
@@ -17,15 +16,18 @@ Generate **Conventional Commits** messages and pull request descriptions using A
## Features ## Features
- **Interactive menu** — `gai` opens a menu, select actions with ↑/↓ + space/enter - **🤖 AI Commit Messages** — generate Conventional Commits from staged diffs with project context
- **Context-aware commits** — reads project overview, staged diff, and recent commit history - **🔀 AI Pull Requests** — create GitHub, Gitea, or GitLab PRs with AI-generated title and body
- **Conventional Commits** — `feat(scope): description` format by default - **📖 Explain Changes** — `gai explain` explains diffs in plain language
- **Interactive file selection** — ↑/↓ to navigate, space to select, top-level "Select all" - **🔍 Code Review** — `gai review` provides thorough, constructive code review
- **Inline editing** — edit AI-generated messages right in the terminal with cursor movement - **📝 Changelog Generation** — `gai changelog` generates user-facing changelogs from commits
- **AI-generated PRs** — create GitHub, Gitea, or GitLab pull requests with generated title and body - **💡 Smart Suggestions** — `gai suggest` recommends branch names or commit types
- **OpenAI-compatible API** — works with DeepSeek, OpenAI, Ollama, OpenRouter, and more - **✏️ Amend Commits** — `gai commit --amend` amends with AI-generated message
- **Review before commit** — confirm, edit, or abort the generated message - **⚡ Streaming Output** — AI responses stream token-by-token for instant feedback
- **Bun-native runtime** — built on Bun APIs with no runtime npm dependencies - **📂 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 ## Quick Start
@@ -39,85 +41,186 @@ gai config
# Open interactive menu # Open interactive menu
gai gai
# Or directly generate a commit message # Generate a commit message
gai commit gai commit
# Or create an AI-generated pull request # Explain your changes
gai pr gai explain
``` ```
## Usage ## Usage
``` ```
gai Open interactive menu gai Open interactive menu
gai commit Generate commit message (interactive file selection) gai commit Generate AI commit message (interactive file selection)
gai commit --auto Auto-stage all changed files gai commit -a Auto-stage all changed files
gai commit -d Generate message without committing 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 Create a PR with AI-generated title and body
gai pr --draft Create a draft PR gai pr --draft Create a draft PR
gai config Configure API settings gai explain Explain staged changes in plain language
gai --help Show help 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 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 ### Interactive Menu
``` ```
$ gai $ gai
gai gai
Choose a workflow AI-powered git helper — choose a workflow
↑/↓ navigate · enter/space select · ctrl+c cancel ↑/↓ navigate · enter/space select · ctrl+c cancel
❯ ● commit Generate AI commit message ❯ ● commit Generate AI commit message
○ pr Create a PR with AI-generated title ○ pr Create a PR with AI-generated title
○ explain Explain staged changes in plain language
○ review AI code review of staged changes
○ changelog Generate changelog from commits
○ suggest Suggest branch name or commit type
○ amend Amend last commit with AI message
○ config Configure API settings ○ config Configure API settings
``` ```
### Commit Flow ### Command Examples
``` #### Commit
$ gai commit
Staged files (will be included):
✓ src/git.ts (modified)
Select files to stage:
2 unstaged files available
↑/↓ navigate · space toggle · enter confirm · ←/backspace back · ctrl+c cancel
❯ □ Select all
□ src/ai.ts modified
■ src/newfile.ts new
Generating commit message...
Generated commit message:
feat(git): add interactive file staging and commit wrapper
Use this message? [Y/n/e] Y
✔ Committed successfully!
[main a3f7c2b] feat(git): add interactive file staging and commit wrapper
1 file changed, 45 insertions(+), 12 deletions(-)
```
### Pull Request Flow
`gai pr` detects the remote platform from `origin`:
- GitHub remotes use the `gh` CLI
- Gitea remotes use the `tea` CLI
- GitLab remotes use the `glab` CLI
- Unknown remotes prompt you to choose a platform
The command compares your current branch against the default branch, pushes the branch if needed, generates a PR title/body from the branch commits and diff, then asks for confirmation before creating the PR.
```bash ```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 gai pr
# Draft PR
gai pr --draft 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 ## Configuration
### Via `gai config` (interactive) ### Via `gai config` (interactive)
@@ -126,6 +229,15 @@ gai pr --draft
gai config 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 ### Via environment variables
| Variable | Default | Description | | Variable | Default | Description |
@@ -193,13 +305,14 @@ GAI_MODEL=anthropic/claude-sonnet-4
│ │ │ │
│ 2. Collect code changes │ │ 2. Collect code changes │
│ ├─ git diff --staged for commits │ │ ├─ git diff --staged for commits │
│ └─ branch diff for pull requests │ │ ├─ Branch diff for pull requests │
│ └─ Pipe support for external diffs │
│ │ │ │
│ 3. Collect commit history │ │ 3. Collect commit history │
│ ├─ git log --oneline -10 for commits │ │ ├─ git log --oneline -10 for commits │
│ └─ branch commits for pull requests │ │ └─ Branch commits for pull requests │
│ │ │ │
│ 4. Build prompt → Call AI API │ │ 4. Build prompt → Call AI API (streaming) │
│ │ │ │
│ 5. Review → Confirm → Commit or Create PR │ │ 5. Review → Confirm → Commit or Create PR │
└─────────────────────────────────────────────┘ └─────────────────────────────────────────────┘
package.json
+2 -2
View File
@@ -1,7 +1,7 @@
{ {
"name": "gai", "name": "gai",
"version": "0.1.2", "version": "0.2.0",
"description": "AI-powered git commit message generator", "description": "AI-powered git helper — commit messages, PRs, code review, changelogs, and more",
"module": "index.ts", "module": "index.ts",
"type": "module", "type": "module",
"bin": { "bin": {