# diffscribe

> AI-powered commit message generator for Conventional Commits

Latest version **1.0.3** (published 2026-02-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install diffscribe
pnpm add diffscribe
yarn add diffscribe
bun add diffscribe
```

Provides the command `dcs`.

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.3 |
| Published | 2026-02-02 |
| First published | 2026-02-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20 |
| Dependencies | 7 |
| Unpacked size | 41.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Raghav Gaba |
| Maintainers | raghavvvgaba |
| Keywords | git, commit, conventional-commits, cli, ai, diffscribe, dcs |

## Links

- npm: https://www.npmjs.com/package/diffscribe
- Repository: https://github.com/raghavvvgaba/diffscribe
- Homepage: https://github.com/raghavvvgaba/diffscribe#readme
- Issues: https://github.com/raghavvvgaba/diffscribe/issues
- npm.io page: https://npm.io/package/diffscribe

## Dependencies (7)

- [chalk](https://npm.io/package/chalk.md) ^5.4.1
- [execa](https://npm.io/package/execa.md) ^9.5.2
- [dotenv](https://npm.io/package/dotenv.md) ^17.2.3
- [commander](https://npm.io/package/commander.md) ^12.1.0
- [clipboardy](https://npm.io/package/clipboardy.md) ^4.0.0
- [@openrouter/sdk](https://npm.io/package/@openrouter/sdk.md) ^0.5.1
- [@inquirer/prompts](https://npm.io/package/@inquirer/prompts.md) ^7.2.0

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 1.0.3 (latest) — 2026-02-02
- 1.0.2 — 2026-02-02
- 1.0.1 — 2026-02-02

## README

# 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

### Global Installation (Recommended)

```bash
npm install -g diffscribe
```

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

```bash
dcs        # If installed globally
```

### Zero-install via npx

```bash
npx diffscribe
```

## Setup

### 1. Get OpenRouter API Key

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

### 2. Set Environment Variable

```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. Verify Setup

```bash
echo $OPENROUTER_API_KEY
```

## Usage

### Basic Usage

```bash
# Stage your changes
git add .

# Generate commit message (if installed globally)
dcs

# Or using npx
npx diffscribe
```

### Mock Mode (Testing)

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:

### Draft Stage (Free Models)
- **Primary**: `mistralai/devstral-2512:free` — Fast free model for initial commit message
- **Backup**: `qwen/qwen3-coder:free` — Falls back if primary hits rate limits

### Refinement Stage (Paid Model)
- **Refinement**: `google/gemini-2.5-flash-lite` — Polishes messages for large diffs (300+ lines or 12KB+)

### When Does Refinement Run?
Only for larger changes to improve clarity and structure. Smaller diffs skip refinement to save cost.

## Options

```
### dcs

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

### Examples

```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

---
_Source: https://npm.io/package/diffscribe · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._