diffscribe

AI-powered commit message generator for Conventional Commits.

Features

- ✅ Conventional Commits compliance
- ✅ Concise and detailed modes
- ✅ Preview before committing
- ✅ Automatic clipboard copy
- ✅ Regeneration loop
- ✅ Smart model selection (free draft + paid refinement for long diffs)
- ✅ Mock mode for testing
- ✅ Error handling with clear messages

How It Works

1. Reads your staged Git diffs
2. Generates a Conventional Commit message using AI
3. Preview and accept/reject
4. Copies to clipboard on accept
5. Run git commit and paste message

Installation

$3

``bash
npm install -g diffscribe
`

After installation, you can run the dcs command from anywhere:

`bash
dcs # If installed globally
`

$3

`bash
npx diffscribe
`

Setup

$3

Visit https://openrouter.ai/keys to get your API key.

$3

`bash
export OPENROUTER_API_KEY=your-api-key-here
`

For permanent setup, add to your shell profile:
`bash
echo 'export OPENROUTER_API_KEY=your-api-key-here' >> ~/.bashrc # or ~/.zshrc
source ~/.bashrc
`

$3

`bash
echo $OPENROUTER_API_KEY
`

Usage

$3

`bash


Stage your changes

git add .

Generate commit message (if installed globally)

dcs

Or using npx

npx diffscribe
`

$3

For testing without API calls:

`bash
dcs --mock # If installed globally
npx diffscribe --mock # Using npx
`

Model Strategy

The tool uses a smart two-stage approach for optimal cost and quality:

$3


- Primary: mistralai/devstral-2512:free — Fast free model for initial commit message
- Backup: qwen/qwen3-coder:free — Falls back if primary hits rate limits

$3

- Refinement: google/gemini-2.5-flash-lite — Polishes messages for large diffs (300+ lines or 12KB+)

$3

Only for larger changes to improve clarity and structure. Smaller diffs skip refinement to save cost.

Options

`


$3

Generate AI-powered commit messages for your staged changes.

`bash
dcs [options]
`

Options:
-V, --version output the version number
--mock Use mock generation instead of LLM (for testing)
-h, --help display help for command

$3

`bash


Generate commit message with AI

dcs

Test without API calls

dcs --mock

Using npx (no installation needed)

npx diffscribe
npx diffscribe --mock
`
`

Requirements

- Node.js >= 20
- Git repository
- OpenRouter API key (unless using --mock mode)

Development

`bash


Install dependencies

npm install

Build

npm run build

Watch mode

npm run dev

Type check

npm run typecheck
``

License

MIT