Changelogger

Find CHANGELOG.md URLs for npm packages. Helpful for agents and tools that need to gather all the changes between outdated packages. See SKILL.md for details

Why?

This tool is slightly different from the other tools I found that do this in that:

• Doesn’t require GitHub Auth
• Works with nested packages (/repo/packages/package-name/CHANGELOG.md)
• Falls back to "GitHub compare" tags URLs

Installation

uv tool install git+https://github.com/jamesdoyle/changelogger
# Or from the PIPY:
uv tool install changelogger # not working yet!!

Or build and install locally:

git clone https://github.com/jamesdoyle/changelogger
cd changelogger
uv sync
# then install globally
uv tool install .

Usage

# if installed as a tool
changelogger <package_name> [package_name2 ...]

# or when cloned, run directly with Python
uv run python changelogger.py <package_name> [package_name2 ...]

Examples

Use getting the URL:

# when installed globally
changelogger next-sanity-image
# or when cloned, run directly with Python
uv run python changelogger.py next-sanity-image

# Multiple packages
changelogger next-sanity-image sanity-plugin-iframe-pane

# Nested package (handled automatically)
changelogger sanity-plugin-iframe-pane

# With verbose logging
changelogger lodash --verbose

Via the skill:

# save the skill file in the global skills folder
curl -O "https://raw.githubusercontent.com/james2doyle/changelogger/refs/heads/main/SKILL.md" "$HOME/.agents/skills/smart-package-upgrade/SKILL.md"
# then in your agent:
/smart-package-upgrade

Running in an agent without the skill:

! npm outdated @biomejs/biome --json
! changelogger @biomejs/biome
> Fetch the changelog from the URL and use that to determine the upgrade from the current version to the latest one

Example Output

changelogger next-sanity-image sanity-plugin-iframe-pane
# outputs these urls
https://raw.githubusercontent.com/lorenzodejong/next-sanity-image/refs/heads/main/CHANGELOG.md
https://raw.githubusercontent.com/sanity-io/plugins/refs/heads/main/plugins/sanity-plugin-iframe-pane/CHANGELOG.md

How It Works

This tool uses multiple methods to find the CHANGELOG.md URL, trying each in order until one succeeds:

1. unpkg.com - Check if the package publishes CHANGELOG.md directly to npm
2. npm view bugs URL - Extract GitHub repo from package metadata and construct raw URL
3. npm repo - Use npm's repo command to get full path (handles nested monorepo packages)
4. GitHub compare URL - If the package is installed locally and outdated, return a compare URL showing commits between versions

For GitHub URLs, both main and master branches are tried. For compare URLs, both tag formats (1.0.0 and v1.0.0) are tried.

Development

# Install dependencies
uv sync

# Run tests
uv run pytest test_changelogger.py -v

# Type checking
uv run basedpyright changelogger.py

# Linting
uv run ruff check changelogger.py

Publishing

To publish a new version of changelogger to PyPI:

1. Build the project:

This creates the source distribution and wheel in the dist/ directory.

uv build

2. Publish to PyPI:

You will need a PyPI API token.

uv publish

AI Integration

This repository includes documentation a SKILL.md with instructions for AI agents to use changelogger when helping users upgrade npm packages.

The SKILL.md document provides a complete workflow for package upgrades:

1. Identify outdated packages
2. Fetch changelog URLs with changelogger
3. Analyze changelogs for breaking changes
4. Plan and execute migrations

AI agents can use this tool to provide informed upgrade guidance by fetching and summarizing relevant changelog entries between package versions.

OpenCode Custom Command

You can create a custom command in OpenCode to easily fetch and summarize changelogs without leaving your terminal.

Create a file named changelog.md in your ~/.config/opencode/commands/ (global) or .opencode/commands/ (project-local) directory:

---
description: Find and summarize recent updates for an npm package to better help with package upgrades
subtask: true
---

I need to know the recent changes for given npm package/packages: `$ARGUMENTS`.

First, gather the details about the current packages:

```bash
npm outdated $ARGUMENTS --json
```

Then, use your bash tool to execute the `changelogger` CLI to find CHANGELOG URLs:

```bash
changelogger $ARGUMENTS
```

If the URL is not found, STOP and report the problem.

Now, analyze the changelog, pay attention to:

1. **Version headers** - Look for the versions between current and target
2. **BREAKING CHANGE** labels - These require code modifications
3. **Deprecation notices** - APIs that will be removed in future versions
4. **Migration guides** - Step-by-step upgrade instructions
5. **Peer dependency changes** - May require updating related packages

Once saved, you can run this inside the OpenCode TUI:

/changelog lodash

License

MIT