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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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.