# Add Desktop Notifications to a Chrome Extension

Yes. An agent adds the notifications permission, a notify helper, an options toggle and click-to-focus to your MV3 extension, tests it with Jest, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-notifications/chrome-extension/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the extension's three contexts before it adds a notification to any of them. In an extension shaped like chibat/chrome-extension-typescript-starter, `public/manifest.json` is Manifest V3 with `permissions: ["storage"]`, `host_permissions` for all URLs, a service worker at `js/background.js`, a popup, an options page and one content script. `src/background.ts` is a `polling()` function that reschedules itself with `setTimeout` every 30 seconds and does nothing else. `src/popup.tsx` is a React 18 component that writes a counter to the action badge with `chrome.action.setBadgeText` and sends `{ color: "#555555" }` to the active tab with `chrome.tabs.sendMessage`; `src/content_script.tsx` receives it, sets `document.body.style.backgroundColor`, and answers with a string. `src/options.tsx` stores `favoriteColor` and `likesColor` in `chrome.storage.sync` and shows `Options saved.` for a second.

The build and test setup decide where new code goes. `webpack/webpack.common.js` has four entries, `popup`, `options`, `background` and `content_script`, emits to `dist/js`, splits shared modules into `vendor.js` for every chunk except `background`, and copies `public/` to `dist/`, which is why `icon.png` ends up beside the HTML files and why a notification can name it as `iconUrl`. `jest.config.js` sets `roots: ["src"]` and runs `.ts` files through `ts-jest` with `tsconfig.test.json`; the only test is `src/__tests__/sum.ts`. `@types/chrome` 0.0.158 is a dev dependency, so `chrome.notifications` is typed, and `.github/workflows/build.yml` runs `npm ci`, `npm run build` and `npm test` on Node 20 and 22.

The agent adds `"notifications"` to `permissions`, and `src/notifications.ts` with a `notify({ title, message, tabId })` function that reads a `notificationsEnabled` flag from `chrome.storage.sync`, returns without calling the API when it is off, and otherwise calls `chrome.notifications.create` with `type: "basic"`, `iconUrl: "icon.png"` and the text, remembering the `tabId` for the notification id it gets back. The content script, after it changes a page's background, sends `{ type: "colorChanged", url: location.href }` to the runtime; `background.ts` listens with `chrome.runtime.onMessage` and calls `notify` with the page's URL as the message and `sender.tab.id`, so the user sees which tab changed. `chrome.notifications.onClicked` looks the id up and calls `chrome.tabs.update(tabId, { active: true })` and `chrome.windows.update(windowId, { focused: true })`, then clears the notification. The options page gets a third control, a `Notify me when a page's background changes` checkbox saved beside `favoriteColor`, and the popup's `change background` button needs no change.

Tests run in Jest with a fake `chrome`: `src/__tests__/notifications.ts` sets `globalThis.chrome` to an object with `storage.sync.get` and `notifications.create` as `jest.fn()`, asserts `create` is called with the title, message and `icon.png` when the flag is on, not called when it is off, and that a click on a remembered id calls `chrome.tabs.update` with that tab. The listener wiring in `background.ts` is kept thin so the testable logic lives in `notifications.ts`. The agent runs `npm run build`, `npm test` and `npx prettier --check "src/**/*.{ts,tsx}"`, then loads `dist/` as an unpacked extension in the sandbox's Chromium, clicks `change background` on a page, and screenshots the notification to show the permission and icon resolve.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add desktop notifications to this Manifest V3 Chrome extension and open a pull request. Read public/manifest.json, src/background.ts, src/popup.tsx, src/options.tsx, src/content_script.tsx, webpack/webpack.common.js, jest.config.js, tsconfig.test.json and package.json first. Add the notifications permission. Create src/notifications.ts with a notify function that checks a notificationsEnabled flag in chrome.storage.sync and calls chrome.notifications.create with type basic, iconUrl icon.png, a title and a message, keeping a map from notification id to tab id. Have the content script send a colorChanged message with the page URL after it changes the background, handle it in background.ts by calling notify with the sender's tab id, and on chrome.notifications.onClicked activate that tab and focus its window, then clear the notification. Add a checkbox to the options page that saves notificationsEnabled next to favoriteColor. Add src/__tests__/notifications.ts with a fake chrome object covering enabled, disabled and click. Run npm run build, npm test and prettier --check on src, load dist in a browser and trigger one notification to confirm the icon and permission work, and paste the output in the pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that adds one permission to `public/manifest.json`, a new `src/notifications.ts`, a message in `src/content_script.tsx`, listeners in `src/background.ts`, a checkbox in `src/options.tsx` and a test file under `src/__tests__/`. The description shows the manifest diff first, because a new permission is what a store reviewer and a user both see, then pastes the webpack build, the Jest summary and the Prettier check, with a screenshot of one notification from the sandbox browser.

The repository's `build` workflow runs `npm run build` and `npm test` on Node 20 and 22 on the pull request, so the new test runs as a check in both.

A reviewer checks that the permission list grew by exactly `notifications`, that nothing fires when the option is off, that the map of ids to tabs is cleared when a notification closes, and that the content script sends nothing on pages where it did not change the background. They merge and bump `version` in the manifest when they next publish.

## Run it on every extension that needs to tell the user something

A team maintaining several extensions sends one `POST /o/{org}/sessions` per repository with this prompt and the repository in `resources`. Each run reads that extension's own manifest and background script, so one built with Vite instead of webpack or one that already has an alarm gets the helper fitted to that, and each opens its own pull request.

Send a `request_id` with each call so a retry returns the run already started, and set a `webhook_url` on the key so `run.completed` arrives with `session_url` when the turn ends and your handler can post the pull request where the extension's reviewers read it.

## Why run it on Rush?

A notification touches all three extension contexts and a permission, and the one thing that proves it works is a browser with the unpacked extension loaded, a page whose background changes, and a notification that appears with the right icon. In a Rush sandbox the agent has that browser, loads `dist/`, triggers the flow and keeps the screenshot in the run's record beside the Jest output and the pull request.

By hand this is small edits in five files plus a Jest setup for the `chrome` global that the starter does not have yet. The agent makes the change in one pass with the repository's own build, and a follow-up such as "add an Undo button that restores the old colour" wakes the parked sandbox and lands on the same branch.

## Frequently asked questions

### Why does the manifest need a new permission?

`chrome.notifications` is unavailable until `"notifications"` is in `permissions`, and Chrome shows the new permission to users of an already installed extension on update. The pull request adds exactly that one entry and nothing to `host_permissions`, which already covers all URLs.

### Does the service worker stay alive to show notifications?

It does not need to. A Manifest V3 service worker wakes for `chrome.runtime.onMessage` and for `chrome.notifications.onClicked`, handles the event and may stop again. The map from notification id to tab id is kept in `chrome.storage.session` so a wake-up after idle still knows which tab to focus; the existing `setTimeout` loop in `background.ts` is left as it is.

### How is chrome.notifications tested without a browser?

With a fake: the Jest test assigns `globalThis.chrome` an object whose `storage.sync.get` returns the flag and whose `notifications.create` and `tabs.update` are mocks, then asserts the calls. The logic lives in `src/notifications.ts` so the listener registration in `background.ts` has nothing to test. The real-browser check is the screenshot in the pull request.

### Can users turn it off?

Yes. The options page gains a checkbox stored as `notificationsEnabled` in `chrome.storage.sync`, read by `notify` on every call, so turning it off takes effect without reloading the extension. The default is on so the feature is visible after install.

## More Chrome extension jobs

- [Add a Release Workflow for a Chrome Extension](https://getrush.ai/run/add-release-workflow/chrome-extension/)
- [Add a Side Panel to a Chrome Extension](https://getrush.ai/run/add-side-panel/chrome-extension/)
- [Publish a Chrome Extension to the Chrome Web Store from GitHub Actions](https://getrush.ai/run/add-web-store-publishing/chrome-extension/)

## The same job on other stacks

- [Add Desktop Notifications to an Electron App](https://getrush.ai/run/add-notifications/electron/)
- [Add Native Notifications to a Tauri App](https://getrush.ai/run/add-notifications/tauri/)

## More jobs like this: Hand off a long task

- [Set Up npm Trusted Publishing for a Node.js Package](https://getrush.ai/run/add-npm-trusted-publishing/nodejs/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
