robo-commitizen

robo-commitizen adds an AI-assisted Conventional Commit workflow to an existing package-managed project with a single command.

Quick Start

Install the commit flow into a repo that already has a package.json:

pnpm dlx robo-commitizen add
npx robo-commitizen add
yarn dlx robo-commitizen add
bun x robo-commitizen add

Choose a provider up front if you want to skip the prompt, although it will walk you through this.

pnpm dlx robo-commitizen add --provider openai

Then set your provider credentials and commit as usual:

export OPENAI_API_KEY=sk-...

git add .
git commit

What It Does

• Generates a bunch of files that allow AI to write your commits for you
• Copies the code into your repo so you can change it/have 0 dependencies
• Works with existing Commitizen-style config, or creates a starter config for you
• Supports OpenAI, Gemini, Claude CLI, OpenRouter, and a manual fallback flow
• Tries to install commitizen for you if it is not already in the repo
• Can wire up Husky so plain git commit goes through the AI prompt

Commands

robo-commitizen add

Adds the AI commit workflow to an existing package-managed project.

Options:

• --provider <name>: Choose openai, claude, gemini, or openrouter
• --config <path>: Path to your commitizen config
• --yes: Apply the recommended full setup without prompting

Configuration

robo-commitizen looks for existing config in this order:

• .commit-config.cjs
• .commit-config.js
• .czrc
• .czrc.json
• package.json commitizen config

If nothing is found, it creates .commit-config.cjs with sensible defaults.

It expects to run in a JavaScript or TypeScript package repo with a package.json, since it updates package metadata and installs missing dependencies through npm, pnpm, yarn, or bun.

Example config

module.exports = {
  commitConfig: {
    types: [
      { name: "feat", description: "A new feature" },
      { name: "fix", description: "A bug fix" },
      // ... more types
    ],
    scopes: [
      { name: "api" },
      { name: "ui" },
      // ... more scopes
    ],
  },
};

Environment Variables

Set the credentials for the provider you want to use:

# OpenAI
export OPENAI_API_KEY=sk-...

# Claude CLI (must be installed separately)
# No key needed, uses: claude <command>

# Gemini
export GEMINI_API_KEY=...

# OpenRouter
export OPENROUTER_API_KEY=...

You can also set provider and model defaults:

export CZ_AI_PROVIDER=openai
export CZ_AI_SMALL_MODEL=gpt-5.4-mini
export CZ_AI_BIG_MODEL=gpt-5.4

How It Works

Running robo-commitizen add copies the commit adapter into .robo-cz, updates your Commitizen path, and can install the Husky hook that routes git commit through the AI prompt.

From there, the commit flow looks like this:

git add <files>
git commit
  → Detects staged changes
  → Calls AI with prompt + diff
  → Suggests a conventional commit
  → User confirms or edits
  → Commit created with conventional format

Architecture

robo-commitizen/
├── bin/cli.js              # Entry point
├── src/
│   ├── commands/
│   │   └── add.js          # Main command
│   ├── .robo-cz/           # Runtime files used in this repo
│   ├── templates/          # Config templates
│   ├── detect/             # Config detection
│   ├── install/            # Installation logic
│   └── utils/              # Utilities
└── package.json

Development

npm install

node bin/cli.js add

npm test

License

MIT