Patchwise

AI-assisted Git commits, with you still in charge.

Patchwise is a CLI tool that helps developers turn raw Git changes into clean, structured, and meaningful commits using AI assistance.

It analyzes your diff, suggests commit messages with detailed bodies, and guides you through staging and committing while keeping you fully in control.

Features

• Analyze staged or unstaged changes
• Generate commit messages with body using AI
• Supports Conventional Commits
• Interactive file selection and staging
• Live model selection during setup
• Custom commit message option
• Optional push after commit
• Smart diff truncation for large changesets
• Colorful CLI output with type badges
• Multi-language support (EN / FR)
• Multi-provider: Gemini by default, Groq as an alternative
• Automatic fallback to a secondary provider on transient failures

Use Without Installing

npx patchwise@latest setup

pnpm dlx patchwise@latest setup

bunx --bun patchwise@latest setup

Quick Start

1. Run setup

npx patchwise@latest setup

This interactive wizard will:

• Let you pick a provider — Gemini (recommended) or Groq
• Ask for that provider's API key (get a Gemini key at aistudio.google.com/apikey, or a Groq key at console.groq.com/keys)
• Let you pick a model from the live list of available models
• Optionally configure a fallback provider, used automatically if the primary one fails
• Set your emoji and commit language preferences

Or set your API key(s) manually:

export GEMINI_API_KEY=your_api_key_here
export GROQ_API_KEY=your_api_key_here

2. Stage your changes

git add .

3. Generate and commit

npx patchwise@latest commit

You can use the same pattern for every command:

npx patchwise@latest suggest
pnpm dlx patchwise@latest stage
bunx --bun patchwise@latest commit --yes

Example

npx patchwise@latest commit

────────────────────────────────────────────────
  📝 Commit Suggestions
────────────────────────────────────────────────

  Summary:
  Update project configuration and add payment documentation

  Suggestions:

  1. [CHORE] chore(config): update gitignore and add payment docs
     - Add .gitignore entries for build artifacts
     - Document Genuka Pay integration flow

  2. [DOCS] docs: add payment docs and update gitignore
     - Document payment module structure
     - Ignore generated config files

────────────────────────────────────────────────

Commands

patchwise commit

Generate suggestions and create a commit from staged changes.

npx patchwise@latest commit

Options:

• --all stage all changes before commit
• --select interactively select files
• --push push after commit
• --yes skip confirmations
• --lang <en|fr> commit language
• --provider <name> AI provider
• --model <model> AI model
• --scope <scope> set commit scope
• --no-scope disable scope

patchwise suggest

Generate commit suggestions without committing.

npx patchwise@latest suggest

patchwise stage

Interactively select files to stage.

npx patchwise@latest stage

patchwise setup

Run the interactive setup wizard to configure your AI provider, model, and API key.

npx patchwise@latest setup

patchwise config init

Create a project config file.

npx patchwise@latest config init

Configuration

Environment variables

GEMINI_API_KEY=xxx
GROQ_API_KEY=xxx
PATCHWISE_PROVIDER=gemini
PATCHWISE_MODEL=gemini-2.5-flash
PATCHWISE_LANGUAGE=en

Config file

Create patchwise.config.json:

{
  "provider": "gemini",
  "model": "gemini-2.5-flash",
  "commitConvention": "conventional",
  "language": "en",
  "maxSubjectLength": 72,
  "confirmBeforeCommit": true,
  "confirmBeforePush": true,
  "scopeStrategy": "auto",
  "fallbackProvider": "groq"
}

API keys are never stored in patchwise.config.json (it's meant to be committed to the repo). They live in your user-level config — written by patchwise setup — or in GEMINI_API_KEY / GROQ_API_KEY environment variables.

scopeStrategy

Controls how commit scopes are handled:

• "auto" — AI infers the scope from the diff (default)
• "manual" — you provide a scope via --scope
• "none" — no scope is included in commit messages

Conventional Commits

Patchwise generates commits following this format:

type(scope): subject

body (optional)

Supported types: feat, fix, refactor, docs, test, chore, perf, build, ci

Examples:

feat(auth): add email verification flow
fix(api): handle null company id
refactor(ui): simplify sidebar logic
docs(readme): update installation guide

chore(config): update gitignore and add payment docs

- Add .gitignore entries for build artifacts
- Document Genuka Pay integration flow

AI Providers

Supported:

• Gemini (default, with live model selection)
• Groq (with live model selection)

Configure a fallbackProvider (via patchwise setup or patchwise.config.json) and Patchwise automatically retries with it if the primary provider is rate-limited, unreachable, or temporarily down — auth failures and oversized requests don't trigger a retry, since those usually have the same cause on every provider.

Planned:

• OpenAI
• Ollama
• Anthropic

Architecture

CLI
 ├── Git Layer
 ├── AI Layer (provider-agnostic)
 ├── Commit Engine (diff, format, truncation)
 ├── Config System (env + project + user)
 └── UI Layer (colors, prompts, output)

Safety

• No commit without user validation
• No push without confirmation unless explicitly requested
• API keys are not stored in the project
• Only staged changes are used by default
• Smart diff truncation prevents token limit errors

Development

Install dependencies:

pnpm install

Run in development:

pnpm dev

Build:

pnpm build

Lint + typecheck:

pnpm check:ci

Tests:

pnpm test

Contributing

See CONTRIBUTING.md for details.

• open an issue
• submit a pull request
• improve documentation
• propose features

License

MIT

Philosophy

Patchwise does not replace Git.

It helps you write better commits, keep history clean, and move faster without losing control.

Support

If you find the project useful, consider starring the repository.