Metadata-Version: 2.4
Name: changewatch
Version: 0.1.0
Summary: A doorbell for your published work. Tells you when somebody else cites, stars, files or mentions it - and stays silent the rest of the time.
Author-email: Vincent Gonzalez <hello@f-keys.com>
License: MIT
Project-URL: Homepage, https://github.com/vince-gonzalez/changewatch
Project-URL: Source, https://github.com/vince-gonzalez/changewatch
Project-URL: Issues, https://github.com/vince-gonzalez/changewatch/issues
Keywords: citations,openalex,orcid,zenodo,github,monitoring,research,notifications,altmetrics
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

```
╔══════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                                                                  ║
║   ██████╗██╗  ██╗ █████╗ ███╗   ██╗ ██████╗ ███████╗██╗    ██╗ █████╗ ████████╗ ██████╗██╗  ██╗  ║
║  ██╔════╝██║  ██║██╔══██╗████╗  ██║██╔════╝ ██╔════╝██║    ██║██╔══██╗╚══██╔══╝██╔════╝██║  ██║  ║
║  ██║     ███████║███████║██╔██╗ ██║██║  ███╗█████╗  ██║ █╗ ██║███████║   ██║   ██║     ███████║  ║
║  ██║     ██╔══██║██╔══██║██║╚██╗██║██║   ██║██╔══╝  ██║███╗██║██╔══██║   ██║   ██║     ██╔══██║  ║
║  ╚██████╗██║  ██║██║  ██║██║ ╚████║╚██████╔╝███████╗╚███╔███╔╝██║  ██║   ██║   ╚██████╗██║  ██║  ║
║   ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝ ╚═════╝ ╚══════╝ ╚══╝╚══╝ ╚═╝  ╚═╝   ╚═╝    ╚═════╝╚═╝  ╚═╝  ║
║                                                                                                  ║
║                                a doorbell for your published work                                ║
║                                                                                                  ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════╝
```
You can already see what you did. What you cannot see is whether anyone else
did anything about it.

The first citation. The first star from a stranger. The first time your name
appears somewhere you did not put it. That signal has no instrument -
everything that exists reports totals, and a total that moves by three is
indistinguishable from noise until you have watched it for a month.

**This is a doorbell, not a dashboard.** Almost every run says nothing
happened and exits.

```
pip install changewatch
changewatch init          # writes a config to fill in
changewatch check         # says only what is new
```

## The two rules

**1. Only what somebody else did.** Your own commits, releases and citations
are not news. You made them.

**2. A counter is not an event.** Downloads wander. A number is worth saying
only when it steps, and the step is measured against what that number normally
does - three more downloads on a package with four is a story, three more on a
package with four thousand is Tuesday.

## Why the first rule is the whole design

The first ORCID this was pointed at reported **six citations**.

All six were the author citing himself, doubled because Zenodo mints a DOI per
version. Six is a number that feels like an audience. The real figure was
zero.

A tool that cannot tell your own activity from a stranger's will ring on your
own deposits, get muted inside a week, and then be silent on the day something
real happens. So every source checks: your ORCID, your names, your logins.

## What it watches

| Source | What rings | Key |
|---|---|---|
| **OpenAlex** | a work cites yours, by anyone who is not you | none |
| **GitHub** | a star, fork, watcher, issue or PR from a stranger | `GITHUB_TOKEN` |
| **Hacker News** | your exact phrase appears | none |
| **Zenodo** | views or downloads step | none |
| **PyPI / npm** | weekly downloads step | none |

`GITHUB_TOKEN` is required, not optional - those endpoints answer `401`
without one. In a workflow the built-in `secrets.GITHUB_TOKEN` already works.

**Not reachable:** Bluesky and Reddit both answer `403` to unknown clients as
of August 2026, and X is paid-only. Measured, not assumed.

## It does not trust the search engine

Algolia tokenises inside quotes. Asked for `"openapi-drift"` it returns a
thread titled *"How do you catch OpenAPI drift before the UI breaks?"* - two
words, five months old, about nobody's package.

So every hit is checked against the text locally before it counts. Search
engines have their own idea of a phrase and it is not yours.

## The first run is silent

It has nothing to compare against, so everything looks new - including that
five-month-old thread. A doorbell that announces months of history the moment
it is plugged in gets unplugged. The first run learns; the second one rings.

## In CI

```yaml
- run: pip install changewatch
- run: changewatch check
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

Commit `.changewatch-state.json` so the schedule remembers between runs.

## Licence

MIT.
