npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

diff-intent

v1.0.2

Published

AI-powered git diff analysis - understand the intent behind code changes

Readme

diff-intent

AI-powered git diff analysis - understand the intent behind code changes

npm version License: MIT

diff-intent analyzes your git diffs using LLMs to explain:

  • Purpose: What the change is trying to accomplish
  • Change Type: Whether it's a refactor or behavior change
  • Risks: What could break
  • Tests: What tests should exist

Why I built this

We ship more code than ever, and AI has accelerated that even further. But while diffs tell us exactly what changed, they often fail to explain why the change was made, what tradeoffs were considered, or how it fits into the broader system.

I noticed this gap most clearly when reviewing AI-assisted changes. The code looked fine, but the intent—the reasoning—was missing.

This tool came out of that frustration. It’s meant to live alongside your existing git workflow and surface the intent behind a change before you dive into the details. Nothing magical, nothing automatic—just a clearer starting point for understanding code.

diff-intent is my attempt to make code review feel more like reading a design note than staring at raw hunks of text.

Features

  • Multi-provider support: Groq (FREE), OpenAI, Anthropic
  • Flexible input: Staged changes, commits, branches, or piped diffs
  • Beautiful output: Colored terminal, Markdown, GitHub, or JSON
  • Smart caching: 24-hour response cache to save API calls
  • Interactive mode: Ask follow-up questions about security, performance, etc.

Screenshots

Side-by-side diff and intent summary:

diff-intent CLI output

CLI analysis of a diff:

diff-intent side-by-side view

Workflow example:

diff-intent workflow

Quick Start

# Install globally
pnpm add -g diff-intent
# or: npm install -g diff-intent

# Set up an API key (Groq is free!)
export GROQ_API_KEY=your-key-here

# Analyze staged changes
diff-intent

# Analyze last commit
diff-intent HEAD~1

# Analyze a branch
diff-intent main..feature-branch

Installation

pnpm add -g diff-intent
# or
npm install -g diff-intent

API Keys

diff-intent auto-detects available providers from environment variables:

| Provider | Environment Variable | Default Model | Pricing | | --------- | -------------------- | ---------------- | ---------------- | | Groq | GROQ_API_KEY | llama-3.3-70b | FREE tier | | OpenAI | OPENAI_API_KEY | gpt-4o-mini | ~$0.15/1M tokens | | Anthropic | ANTHROPIC_API_KEY | claude-3-5-haiku | ~$0.80/1M tokens |

Get a free Groq API key at console.groq.com

Usage

Basic Commands

# Analyze staged changes (default)
diff-intent

# Analyze specific commits
diff-intent HEAD~1              # Last commit
diff-intent HEAD~3              # Last 3 commits
diff-intent abc123              # Specific commit

# Compare branches
diff-intent main..feature       # Branch comparison
diff-intent origin/main..HEAD   # Compare to remote

# From file
diff-intent --file changes.diff

# Piped input (legacy mode)
git diff | diff-intent

Analysis Modes

Default (Overview): Analyzes the entire diff and provides a high-level summary - the big picture of what changed and why.

diff-intent HEAD~1
# Returns: Overall purpose, change type, key risks, general test areas

Per-file (Detailed): Analyzes each file separately with detailed, specific insights.

diff-intent HEAD~1 --per-file
# Returns: Specific functions changed, edge cases, concrete test cases

Use --per-file when you need to understand the specifics of each file's changes, especially for code review.

Options

diff-intent [target] [options]

Options:
  -p, --provider <provider>  LLM provider (groq, openai, anthropic)
  -m, --model <model>        Specific model to use
  -f, --format <format>      Output format (terminal, markdown, json, github)
  --file <path>              Read diff from file
  --no-color                 Disable colored output
  --per-file                 Analyze each file separately (detailed mode)
  -s, --side-by-side         Show diff and intent side by side
  --show-cost                Show token count and cost estimate
  -i, --interactive          Enable follow-up questions
  --no-cache                 Bypass response cache
  -V, --version              Output version number
  -h, --help                 Display help

Subcommands

# Interactive setup wizard
diff-intent init

# Show current configuration
diff-intent config

# Clear response cache
diff-intent config --clear

Output Formats

Terminal (default for TTY)

╭──────────────────────────────────────────────────────╮
│  Diff Intent Analysis                                │
╰──────────────────────────────────────────────────────╯

  Purpose
  ├─ Refactor authentication flow for better security
  └─ Add rate limiting to prevent abuse

  Change Type
  └─ Behavior change

  Risks
  ├─ Existing sessions may be invalidated
  └─ API response format changed

  Suggested Tests
  ├─ Test rate limit triggers after 100 requests
  └─ Test session persistence across deploys

JSON

diff-intent --format json
{
  "purpose": ["Refactor authentication flow"],
  "changeType": ["Behavior change"],
  "risks": ["Existing sessions may be invalidated"],
  "tests": ["Test rate limit triggers"]
}

GitHub (for PR comments)

diff-intent --format github

Outputs collapsible sections with checkboxes for suggested tests.

Markdown

diff-intent --format markdown

Configuration

Create .diff-intentrc.json in your project root:

{
  "provider": "groq",
  "outputFormat": "terminal",
  "cache": true,
  "showCost": false
}

Or use the setup wizard:

diff-intent init

Configuration Options

| Option | Type | Default | Description | | -------------- | ------- | ---------------- | ----------------------- | | provider | string | auto-detect | LLM provider | | model | string | provider default | Specific model | | outputFormat | string | terminal | Default output format | | cache | boolean | true | Enable response caching | | cacheTTL | number | 24 | Cache TTL in hours | | showCost | boolean | false | Show token/cost info | | colors | boolean | true | Enable colored output | | customPrompt | string | - | Custom system prompt |

Supported Config Files

  • .diff-intentrc
  • .diff-intentrc.json
  • .diff-intentrc.yaml
  • .diff-intentrc.js
  • diff-intent.config.js
  • package.json (diff-intent key)

GitHub Actions

Automatically analyze PRs and post a comment with the diff intent summary.

Setup

  1. Add your API key as a GitHub Secret

    • Go to repo Settings → Secrets → Actions
    • Add GROQ_API_KEY (or OPENAI_API_KEY / ANTHROPIC_API_KEY)
  2. Generate the workflow (recommended)

    diff-intent init
    # Select "Add GitHub Actions workflow for PR analysis"
  3. Or create manually at .github/workflows/diff-intent.yml:

name: Diff Intent Analysis

on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Analyze PR diff
        env:
          GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
        run: |
          git fetch origin ${{ github.base_ref }} --depth=1
          git diff origin/${{ github.base_ref }}...HEAD | npx diff-intent@latest --format github > analysis.md

      - name: Comment on PR
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          header: diff-intent
          path: analysis.md

How It Works

  • One comment per PR - Uses sticky comments that update on each push (not spam)
  • Overview by default - High-level summary of all changes
  • Per-file mode - Add --per-file for detailed analysis of each file (can be verbose for large PRs)

Interactive Mode

Ask follow-up questions about your diff:

diff-intent -i

After the initial analysis, you can explore:

  • Security implications
  • Performance impact
  • Breaking changes
  • Alternative approaches

Examples

Analyze a security fix

diff-intent --file examples/security-fix.diff --show-cost

Per-file analysis of a large PR

diff-intent main..feature --per-file

Side-by-side view

diff-intent HEAD~1 --side-by-side

Use a different provider

diff-intent --provider openai --model gpt-4o

Troubleshooting

"No API key found"

Set at least one API key:

export GROQ_API_KEY=your-key
export OPENAI_API_KEY=your-key
export ANTHROPIC_API_KEY=your-key

"No staged changes"

Either stage your changes:

git add .
diff-intent

Or specify a target:

diff-intent HEAD~1

Cache issues

Clear the cache:

diff-intent config --clear

Or bypass for a single request:

diff-intent --no-cache

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

For questions or feedback, open an issue or email [email protected].

License

MIT - see LICENSE for details.