Skip to content

README.md

Latest commit

 

History

History
250 lines (186 loc) · 9.11 KB

README.md

File metadata and controls

250 lines (186 loc) · 9.11 KB
 ██████╗ ██╗████████╗    ██╗  ██╗ █████╗ ██████╗ ██████╗ ███████╗███╗   ██╗███████╗
██╔════╝ ██║╚══██╔══╝    ██║  ██║██╔══██╗██╔══██╗██╔══██╗██╔════╝████╗  ██║██╔════╝
██║  ███╗██║   ██║       ███████║███████║██████╔╝██████╔╝█████╗  ██╔██╗ ██║███████╗
██║   ██║██║   ██║       ██╔══██║██╔══██║██╔═══╝ ██╔═══╝ ██╔══╝  ██║╚██╗██║╚════██║
╚██████╔╝██║   ██║       ██║  ██║██║  ██║██║     ██║     ███████╗██║ ╚████║███████║
 ╚═════╝ ╚═╝   ╚═╝       ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝     ╚══════╝╚═╝  ╚═══╝╚══════╝

npm version npm downloads license last commit PRs welcome

SGT is a CLI tool that analyzes your staged git changes and generates AI-powered commit message suggestions.
It supports multiple LLM providers, saves your preferences, and handles API key fallbacks automatically.

Requirements

  • Node.js 18 or higher
  • At least one API key for Gemini, Claude, or OpenRouter — or Ollama running locally

Installation

Install globally from npm:

npm install -g sgt-cli

Then run from anywhere inside any git project:

sgt

Or clone and build manually:

# HTTPS
git clone https://github.com/Cat-Div7/commit-suggester.git

# SSH
git clone git@github.com:Cat-Div7/commit-suggester.git

cd commit-suggester
npm install
npm run build
npm link

Providers

  • Gemini — native SDK via @google/generative-ai — free tier available at aistudio.google.com/app/apikey
  • Claude — native SDK via @anthropic-ai/sdk — API keys at console.anthropic.com
  • OpenRouter — popular model list + custom model entry — free models available at openrouter.ai/keys
  • Ollama — runs locally, no API key required — download at ollama.com/download

First Run

On first run SGT will ask you to:

  1. Select a provider
  2. Select or enter a model
  3. Enter your API key

All of these are saved automatically. From the second run onwards SGT goes straight to analyzing your diff and generating suggestions.

API Keys

SGT checks for API keys in this order:

  1. Environment variables (.env file or shell env)
  2. Saved config at ~/.config/sgt-cli/config.json
  3. Prompt — saved after first entry

You can add multiple fallback keys per provider. If the primary key hits a quota limit or auth error, SGT automatically tries the next one.

Copy .env.example to .env and fill in your keys:

cp .env.example .env
SGT_GEMINI_KEY=
SGT_CLAUDE_KEY=
SGT_OPENROUTER_KEY=

OpenRouter Models

On first run with OpenRouter, SGT presents a list of popular models to choose from. You can also type a custom model name manually. If you enter a custom model, SGT will ask if you want to save it to your list for future runs.

Browse all available model IDs at openrouter.ai/models — copy the exact ID including the :free suffix for free models, for example google/gemma-3-4b-it:free.

Your selected model is saved per provider and reused on the next run.

CLI Flags

Flag Description
sgt Normal run using saved provider, model, and keys
sgt --change-model Re-prompt model selection for current provider
sgt --change-key Re-prompt API key for current provider
sgt --change-provider Re-prompt provider selection
sgt --add-key Add a fallback key for the current provider
sgt --reset Clear all saved config and start fresh
sgt --config Show current saved provider, model, and masked keys
sgt --auto-commit Auto pick best suggestion and commit silently
sgt --toggle-welcome Toggle the GIT HAPPENS header on/off
sgt --help, -h Show usage instructions

Important

--auto-commit sends two requests to your AI provider — one to generate suggestions and one to pick the best one. Keep this in mind if you are on a free tier with rate limits.

Saved Config Structure

SGT stores config at ~/.config/sgt-cli/config.json:

{
  "provider": "Gemini",
  "model": {
    "Gemini": "gemini-2.5-flash",
    "OpenRouter": "google/gemma-3-4b-it:free",
    "Claude": "claude-3-5-sonnet-20240620",
    "Ollama": "llama3"
  },
  "keys": {
    "Gemini": ["primary-key"],
    "OpenRouter": ["primary-key", "fallback-key"],
    "Claude": ["primary-key"]
  },
  "customModels": {
    "OpenRouter": ["my-org/custom-model-v1"]
  },
  "showWelcome": true
}

Project Structure

commit-suggester/
├── src/
│   ├── index.ts                  # Entry point
│   ├── main.ts                   # Full flow orchestration
│   ├── constants.ts              # Providers, models, env key map
│   ├── cli/
│   │   ├── flags.ts              # Flag parsing
│   │   └── help.ts               # Help text
│   ├── ui/
│   │   ├── welcome.ts            # Welcome screen — full and bar variants
│   │   ├── prompts.ts            # All inquirer prompts
│   │   └── spinner.ts            # Reusable ora spinner wrapper
│   ├── providers/
│   │   ├── index.ts              # Unified generate() with fallback key retry
│   │   ├── gemini.ts             # Gemini native SDK
│   │   ├── claude.ts             # Claude native SDK
│   │   ├── openrouter.ts         # OpenRouter via fetch
│   │   ├── ollama.ts             # Ollama local
│   │   └── autoCommit.ts        # AI-powered best suggestion picker
│   ├── git/
│   │   ├── checkRepo.ts          # Git repo validation
│   │   └── getDiff.ts            # Staged diff reader
│   ├── config/
│   │   ├── keys.ts               # Key resolution, validation, fallback logic
│   │   ├── models.ts             # Model selection and custom model saving
│   │   └── store.ts              # Single Conf instance
│   └── utils/
│       └── terminalLink.ts       # OSC 8 clickable terminal links
├── dist/                         # Compiled output (gitignored)
├── .env                          # Optional local env (gitignored)
├── .env.example                  # Key names reference
├── package.json
├── tsconfig.json
├── .gitignore
├── LICENSE
├── CONTRIBUTING.md
└── README.md

Scripts

Command Description
npm run build Compile TypeScript to dist/
npm start Run the compiled CLI
npm link Link sgt command globally

Roadmap

  • Phase 1 — Core foundation (store, constants, git helpers, entry point)
  • Phase 2 — Provider integration (Gemini, Claude, OpenRouter, Ollama)
  • Phase 3 — Config and key management (fallback keys, model saving, custom models)
  • Phase 4 — CLI flags (--change-model, --change-key, --reset, --config, etc.)
  • Phase 5 — UX polish (prompts, spinners, provider hints, welcome split, --toggle-welcome)
  • Phase 6 — Release (npm publish, versioning, GitHub release)

Upcoming

  • sgt --setup-alias — set up git sgt alias globally
  • --config display with formatted table (based on user feedback)
  • Web dashboard with AI provider and model usage tracking (post v1.0.0)

Contributing

Contributions are welcome. See CONTRIBUTING.md for the full guide on forking, branching, and opening a PR.

License

MIT — see LICENSE for details.

Author

Omar Ashraf — Cat-Div7