# Project pack: changedetection.io @ 352b036

Facts about **changedetection.io** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> changedetection.io watches websites for you and tells you when something changes. Use it for prices, stock, news, appointment slots, government notices and more. It highlights exactly what changed, can wait for a page to load like a real browser, and sends alerts to email, chat apps and over 80 other services.

## Version and source
- Repository: https://github.com/dgtlmoon/changedetection.io
- Pinned commit: `352b036217e32d3622f282f49bebcdb89592a28c`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/dgtlmoon/changedetection.io/archive/352b036217e32d3622f282f49bebcdb89592a28c.zip
- Official docs: https://github.com/dgtlmoon/changedetection.io/wiki
- Licence: **Apache-2.0**. Free to use, change and share, even commercially. Keep the licence and copyright notices, and note your changes. It includes a patent licence.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/dgtlmoon/changedetection.io bespoke-changedetection
  cd bespoke-changedetection
  git checkout --detach 352b036217e32d3622f282f49bebcdb89592a28c
  # Prepare development requirements and local configuration first.
  pip install -r requirements.txt
  python3 changedetection.py -d ./datastore -p 5000
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run -d --restart always -p "127.0.0.1:5000:5000" -v changedetection-data:/datastore --name changedetection.io dgtlmoon/changedetection.io
  # then open http://localhost:5000
  ```

- Needs: Docker for a trial, Python 3.10+ for development
- Develop: `python3 changedetection.py -d ./datastore -p 5000`
- Test: `pytest`
- Stack: python, javascript (Flask, Playwright, Apprise). Difficulty for a non-developer with an AI: **easy**. A Flask app with a clear folder per feature. Watches, filters and notifications are settings; new processors or notification options are small additions.

## Customisation points (settings → extend → code)
- **watches-and-filters** [settings]: Watch just the price or a stock message. → `In the app, under Edit watch (CSS or XPath selector, text filters, triggers)`
- **notifications** [settings]: Where alerts go and what they say. → `Settings → Notifications`
- **browser-mode** [settings]: Plain request, Playwright or browser steps for login and clicks. → `Settings → Fetching`
- **api** [extend]: Create and manage watches from scripts. → `/api/v1 and docs/api`
- **processors** [code]: Special watch types such as restock or screenshot. → `changedetectionio/processors`

## Must keep working
- Reasonable fetch intervals, so watched sites are not hammered.
- Notification delivery and retry logic.
- Datastore format, so history survives upgrades.

## Staying updatable
Use watches, filters and notifications. For code, add processors or notification handlers as new files.

## Data, costs and safety
- Personal data: **no**. Stored in: JSON files and saved snapshots in the datastore folder. Back up the datastore folder. URLs you watch can reveal your interests.
- Service: Notification services via Apprise (email, Telegram, Discord, Slack and more) (optional, free): Alerts when a page changes.
- Service: Headless browser (Playwright, optional) (optional, free): Load pages that need JavaScript.
- Setting `BASE_URL`: The address used in links inside notifications.
- Setting `PLAYWRIGHT_DRIVER_URL`: Address of a browser container if you use one.
- Respect each site's terms and don't fetch too often.
- Notification URLs can contain tokens. Never paste them into an AI chat.
- Bind it to localhost or add a password before exposing it.

---

# Customising changedetection.io

changedetection.io is a Flask app organised by feature, so finding where something lives is easy.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Web pages (blueprints) | changedetectionio/blueprint/ |
| Watch types | changedetectionio/processors/ |
| Page fetchers | changedetectionio/content_fetchers/ |
| Notifications | changedetectionio/notification/ |
| Storage | changedetectionio/store/ |
| API | changedetectionio/api/ |
| Tests | changedetectionio/tests/ |

## Use the gentlest change first

1. **Settings (no code):** watches, filters, triggers and notification services.
2. **Extend:** the API and Browser Steps.
3. **Code:** processors, fetchers and notification options.

## Recipes

- **New watch type:** add a processor module following the restock one, with its own settings form and diff logic.
- **Custom alert text:** edit the notification body template in Settings → Notifications.

## Running and checking your changes

- Run the app, add a watch for a simple test page, change it and check the alert.
- `pytest` for the area you changed.

## Pitfalls

- Don't run big tests against real sites.
- Keep the datastore folder out of Git.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/changedetection/352b036/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/changedetection/352b036/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/changedetection/352b036/r2/SKILL.md)