GSmart

Your changes. A clear commit message.

GSmart turns your Git diff into an AI-generated Conventional Commit. Review the suggestion, edit it, refine it with feedback, copy it, or commit—all from your terminal.

Quick start · Everyday workflows · Providers · Configuration · Documentation

• Keep the final say. Edit multiline messages, request changes, and restore earlier candidates before committing.
• Choose your AI. Use six hosted providers, ChatGPT subscription login, or local models through Ollama and LM Studio.
• Follow your project's conventions. Share types, scopes, language, and writing instructions, with compatible commitlint rules imported automatically.
• Fit your workflow. Review interactively, generate script-friendly output, or ask for a plan to split mixed changes into coherent commits.

Quick start

You'll need Node.js 22.12.0+, Git 2.25+, and a supported provider or local model.

1. Install

npm install -g gsmart

Prefer another package manager? Use pnpm add -g gsmart or yarn global add gsmart (Yarn Classic).

2. Connect a provider

gsmart login

• OpenAI: choose ChatGPT subscription to sign in through your browser, or API key to paste a key.
• Other hosted providers: paste your API key when prompted.
• Custom / local: enter an OpenAI-compatible base URL and model ID; leave the key blank for a keyless server.

Credentials are saved locally for future runs. Run gsmart login again to add or update a provider.

3. Generate and review

Inside your Git repository, stage the changes you want to describe and run GSmart. Replace the example path with a file you've changed:

git add src/auth.ts
gsmart

An example review session:

✔ Message generated

Candidate #1 (generated):
feat(auth): add password reset
? What would you like to do?
❯ Commit
  Edit message
  Regenerate with feedback
  Browse / restore candidates
  Copy message to clipboard
  Do nothing

Nothing staged yet? Run gsmart and choose files in the interactive picker. Already staged part of a file with git add -p? GSmart uses only that staged diff.

Everyday workflows

# Preview a message and the analyzed files without committing
gsmart --dry-run

# Explain intent that the diff cannot show
gsmart --prompt "This fixes checkout retries after a payment timeout; reference SHOP-142."

# Choose a configured provider and model for this run
gsmart --provider anthropic --model claude-haiku-4-5-20251001

# Generate commit prose in another language
gsmart --language es

# Suggest how to split the existing staged changes into coherent commits
gsmart plan --staged

# Generate from the existing staged diff for a script or editor
gsmart --output message
gsmart --output json

Planning is advisory: it suggests messages, file/hunk groupings, and ordering without changing your repository. See the planning guide for an example.

Choose the right staging behavior

An existing staged diff takes priority in the interactive, --dry-run, and --yes workflows:

Command	If nothing is staged	Creates a commit?
gsmart	Prompts you to select files to stage	If you choose it
gsmart --dry-run	Temporarily stages your selection, then attempts to unstage it	No
gsmart --yes	Stages all detected changes	Automatically
gsmart --output message	Reports an error; does not stage anything	No
gsmart --output json	Returns a JSON error; does not stage anything	No

Dry runs still call the AI provider. Files selected interactively stay staged if you copy the message or choose Do nothing.

For automation, --output message and --output json are prompt-free and leave Git state untouched. Add --stage to explicitly stage all changes, including previously unstaged edits, or --commit to create a commit. These options cannot be combined with --yes or --dry-run. See scripting, stdin, JSON results, and Git hooks.

Providers

Configure providers with gsmart login, then select one with --provider or save a default with gsmart config --default-provider <provider>.

Provider	--provider value	Authentication
OpenAI	openai	ChatGPT subscription or API key
Anthropic	anthropic	API key
Google Gemini	google	API key
Mistral	mistral	API key
Fireworks AI	fireworks	API key
PlataformIA	plataformia	API key
Custom / local	custom	Optional bearer token

Model selection is --model → saved provider model → built-in default. Custom endpoints require a model ID. ChatGPT login and OpenAI API keys have different model access; see authentication and built-in models.

Local inference and custom endpoints

With Ollama installed and its server running:

ollama pull llama3.2
gsmart config --provider custom \
  --base-url http://localhost:11434/v1 \
  --model llama3.2 --clear-api-key
gsmart config --default-provider custom
gsmart --dry-run

Run the last command inside a repository with changes. The custom provider uses OpenAI-compatible Chat Completions. Supply the base URL, including /v1 when required, rather than /chat/completions. See LM Studio setup, optional authentication, and compatibility.

Configuration

Use gsmart config for the interactive menu, or save preferences directly:

gsmart config --default-provider anthropic
gsmart config --provider anthropic --model claude-haiku-4-5-20251001
gsmart config --add-custom-prompt "Use imperative mood and directory names as scopes."
gsmart config --show

To share conventions with your team, commit a .gsmartrc.json at the Git root:

{
  "$schema": "https://raw.githubusercontent.com/ragnarok22/gsmart/main/schemas/gsmartrc.schema.json",
  "types": ["feat", "fix", "docs", "refactor", "test", "chore"],
  "headerMaxLength": 72,
  "language": "en",
  "instructions": "Describe observable changes. Explain why when it is not obvious."
}

Settings resolve per field: CLI options → .gsmartrc.json → compatible commitlint rules → personal settings → built-in defaults. Inspect the result with gsmart config --show-effective. Credentials live in the user-level store, separate from repository conventions.

See the configuration reference for scopes, tickets, breaking changes, history examples, context budgets, and separate profiles.

How it works

Stage or select changes → Generate → Review → Edit, refine, restore, copy, or commit

• AI input: the selected provider receives your diff context, branch name, resolved conventions, and custom instructions. Recent commit subjects are included only when history examples are enabled. Large diffs are reduced locally by default; extra AI summarization is opt-in.
• Review: GSmart validates message syntax and configured rules. You review whether the message accurately describes the change. Earlier candidates remain available during the session.
• Git: before committing, GSmart checks that the staged snapshot still matches the message. Commits use git commit, so hooks still run. Pushing is a separate Git step.

See context controls to inspect or exclude files from AI context. Exclusions affect what the provider sees, not which files are committed.

Command reference

Command	Purpose
gsmart	Generate a message and review it
gsmart plan --staged	Suggest a commit-splitting plan
gsmart login	Configure provider authentication or a custom endpoint
gsmart config	Manage prompts, models, and preferences
gsmart reset	Clear local settings after confirmation
gsmart completions <shell>	Print Bash, Zsh, or Fish completions

Run gsmart --help or gsmart <command> --help for available options. The full command reference lists generation and configuration flags.

Shell completions

For Bash, add eval "$(gsmart completions bash)" to ~/.bashrc. For Zsh, add eval "$(gsmart completions zsh)" to ~/.zshrc after compinit is initialized.

For Fish:

mkdir -p ~/.config/fish/completions
gsmart completions fish > ~/.config/fish/completions/gsmart.fish

Start a new terminal and try gsmart --<Tab> or gsmart --provider <Tab>. See completion setup and updating existing scripts.

Troubleshooting

Problem	First thing to check
Command not found	Confirm the global install succeeded and its executable directory is on PATH.
No provider configured or login expired	Run gsmart login; inspect preferences with gsmart config --show.
No changes found	Run git status and stage the changes you want to describe.
Local model is slow or unreachable	Start the server, verify the URL/model, and increase GSMART_TIMEOUT (milliseconds).
Editor closes before edits appear	Set VISUAL or EDITOR to a command that waits, such as code --wait.
Commit fails	Check Git's diagnostic for identity, signing, or hook errors.

For diagnostic output, run gsmart --debug --dry-run. More remedies are in the troubleshooting guide.

To update, use npm install -g gsmart@latest or pnpm add -g gsmart@latest, then check gsmart --version. See the changelog for release notes.

Documentation

I want to…	Read
Edit, refine, or restore a message	Review workflow and editor setup
Split mixed changes into commits	Advisory commit planning
Integrate with scripts, editors, or hooks	Machine output, JSON schema, and exit codes
Share team conventions	Repository configuration and commitlint
Understand a rejected message	Message validation
Tune large-diff handling	Context budgets, exclusions, and summarization

Development

Use Node.js 22.12.0+ and the pnpm version pinned in package.json:

git clone https://github.com/ragnarok22/gsmart.git
cd gsmart
pnpm install --frozen-lockfile
pnpm run prebuild
pnpm exec tsx src/index.ts --help

Run pnpm run check for lint, typecheck, and tests; pnpm run format:check for formatting; and pnpm run test:coverage for coverage. The development guide covers builds, shell tests, code layout, and model evaluations.

Community

Bug reports, documentation improvements, and pull requests are welcome. Start with the contribution guide. For behavior-changing PRs, include a short CLI transcript showing the result.

Report an issue · Code of conduct · Security policy

Working with AI agents? The companion write-conventional-commit skill gives your coding agent commit-writing guidance:

npx skills add ragnarok22/agent-skills --skill write-conventional-commit

Explore GSmart's star history

License

Licensed under the GNU General Public License v3.0 only.

Built with ❤️ by @ragnarok22.