rayCATCHER

rayCATCHER is a Manifest V3 Chrome extension that records the cf-ray response header for requests whose completed duration is above a configurable threshold.

Manual Installation Outside the Chrome Web Store

Chrome generally blocks direct .crx installs outside the Chrome Web Store for normal consumer profiles. The reliable manual-install path is to load rayCATCHER as an unpacked extension.

Install From the Manual ZIP

1. Use dist/manual/raycatcher-0.1.0-manual-install.zip.
2. Unzip it somewhere permanent, for example ~/Applications/rayCATCHER.
3. Open Chrome and go to chrome://extensions.
4. Enable Developer mode.
5. Click Load unpacked.
6. Select the unzipped rayCATCHER folder, the folder that contains manifest.json.
7. Confirm rayCATCHER is switched On.
8. Set Site access to the level you want. For default behavior, choose On all sites.

Do not delete or move the unpacked folder after loading it. Chrome reads the extension from that folder.

Update a Manual Install

1. Replace the existing unpacked rayCATCHER folder with the new release folder.
2. Go to chrome://extensions.
3. Click the reload button on the rayCATCHER extension card.

Using the same folder path helps Chrome keep the same unpacked extension identity and local data.

Verify a Manual Install

1. Open the rayCATCHER popup.
2. Leave domains set to All.
3. Leave request method set to All.
4. Set Time threshold to 1000 ms and save settings.
5. Visit a request that takes more than one second and includes a cf-ray response header.
6. Open the popup again.

Expected result: the request appears under Logged rays with the domain, timestamp, duration, method, URL, and cf-ray value.

What rayCATCHER Stores

Each capture is stored locally in the extension IndexedDB with:

• cf-ray header value
• domain and full URL
• timestamp
• request method
• request type
• status code
• duration in milliseconds

Settings

Open the extension popup to configure:

• Domains to run on: all domains by default, or a comma separated allowlist
• Request method: all by default, or only GET / POST
• Time threshold: 1000 milliseconds by default

Domain list entries match the exact hostname and subdomains. For example, example.com also matches api.example.com.

Viewing Logs

The popup lists captured rays with the newest entries first. Use the filters to narrow by domain text and minimum request duration, for example 5000 ms.

Privacy

rayCATCHER stores data locally in the browser profile. It does not transmit logs, settings, URLs, request metadata, or cf-ray values to a server.

It does not collect request bodies, response bodies, cookies, credentials, form data, page content, or personal communications.

Build and Test

Run the focused tests:

npm test

Regenerate store assets:

npm run assets:store

Create the Chrome Web Store upload ZIP:

npm run package:store

Create the manual-install ZIP:

npm run package:manual

The generated packages are:

• dist/store/raycatcher-0.1.0-chrome-store.zip
• dist/manual/raycatcher-0.1.0-manual-install.zip

Chrome Web Store Submission

The store submission material is in:

• store/listing.md
• store/privacy-policy.md
• store/reviewer-instructions.md
• store/submission-checklist.md
• store-assets/promotional/small-promo-440x280.png
• store-assets/screenshots/raycatcher-popup-1280x800.png

Before submitting, publish store/privacy-policy.md at a stable HTTPS URL and use that URL in the Chrome Web Store privacy form.

Upload this ZIP in the Chrome Developer Dashboard:

dist/store/raycatcher-0.1.0-chrome-store.zip

Local Development

Load the repo directly in Chrome by opening chrome://extensions, enabling Developer mode, and choosing Load unpacked for this project directory.

There is also an optional runtime verifier:

npm run verify:chrome

The verifier needs a browser build that still supports command-line unpacked extension loading, such as Chromium or Chrome for Testing. If your regular Google Chrome blocks that route, load the extension manually with Load unpacked and use the popup to confirm captures.