# Add Keyboard Shortcuts to a Chrome Extension

Yes. An agent adds manifest commands to your Chrome extension, handles them in the service worker, lists them on the options page, tests the logic and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-keyboard-shortcuts/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 manifest and the four entry points first. In an extension like `chibat/chrome-extension-typescript-starter`, `public/manifest.json` is Manifest V3 with an `action` whose `default_popup` is `popup.html`, an `options_ui` page, a `content_scripts` entry matching `<all_urls>` that loads `js/vendor.js` and `js/content_script.js`, a `background.service_worker` at `js/background.js`, the `storage` permission and `<all_urls>` host permission. `webpack/webpack.common.js` builds `popup`, `options`, `background` and `content_script` from `src/` into `dist/js`, splits a `vendor` chunk for every entry except `background`, and copies `public/` over `dist/`. `src/popup.tsx` is a React 18 component that writes a counter to the badge with `chrome.action.setBadgeText` and sends `{ color: "#555555" }` to the active tab with `chrome.tabs.sendMessage`; `src/content_script.tsx` receives it in `chrome.runtime.onMessage`, sets `document.body.style.backgroundColor` and answers with `sendResponse`. `src/background.ts` only schedules an empty `polling` every 30 seconds, and `src/options.tsx` reads and writes `favoriteColor` and `likesColor` in `chrome.storage.sync`.

Shortcuts live in the manifest under `commands`. The agent adds the reserved `_execute_action` command so a key opens the popup, and a named `toggle-background` command with a `suggested_key` of `Ctrl+Shift+Y` by default and `Command+Shift+Y` on macOS, each with a `description` Chrome shows on its shortcuts page. Chrome lets an extension suggest at most a few defaults, and a suggested key that another extension already holds is left unassigned, so the description text matters and the options page needs to show what is bound.

The handler goes in the service worker. `src/background.ts` gets a `chrome.commands.onCommand.addListener` that, for `toggle-background`, queries the active tab in the current window and sends the same message the popup sends. To keep the popup and the worker in step, the agent moves the message shape into a new `src/messages.ts` with a `colorMessage(color)` builder and a `nextColor(current)` helper that alternates between the tint and the page's own colour, and both `popup.tsx` and `background.ts` import it. The content script answers a `reset` by clearing the inline style rather than leaving the page grey. `src/options.tsx` gains a section that calls `chrome.commands.getAll` and lists each command with its current `shortcut` or an unassigned note, and a link to `chrome://extensions/shortcuts`, which an extension page can open only through `chrome.tabs.create`.

Verification follows `.github/workflows/build.yml`, which runs `npm ci`, `npm run build` and `npm test` on Node 20 and 22. `npm run build` runs webpack in production mode and fails on a type error, and `@types/chrome` at `0.0.158` already declares `chrome.commands`. `npm test` runs Jest through `ts-jest` with `tsconfig.test.json` over `src/`, where `src/__tests__/sum.ts` is the only test, so the agent adds `src/__tests__/messages.ts` for `nextColor` and `colorMessage`, which need no browser, and `src/__tests__/background.ts` with a stubbed `chrome` global whose `commands.onCommand.addListener` captures the listener so the test can fire `toggle-background` and assert on `tabs.sendMessage`. It then loads `dist/` as an unpacked extension in the sandbox's Chromium, presses the shortcut on a page and reads the result.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "A Linear issue labelled agent says: \"Add keyboard shortcuts. One to open the popup and one to toggle the page background, and show the current bindings on the options page.\" Do the work in this repository. Read public/manifest.json, src/background.ts, src/popup.tsx, src/content_script.tsx, src/options.tsx, webpack/webpack.common.js, jest.config.js, tsconfig.test.json, src/__tests__/sum.ts and .github/workflows/build.yml first. Add a commands section to the manifest with _execute_action and a toggle-background command with suggested keys and descriptions. Handle toggle-background in the service worker with chrome.commands.onCommand, sharing the message shape with the popup through a new src/messages.ts, and make the content script able to clear the colour again. On the options page, list each command with its current shortcut from chrome.commands.getAll and a link that opens chrome://extensions/shortcuts in a new tab. Add Jest tests for the message helpers and for the command listener with a stubbed chrome global. Run npm ci, npm run build and npm test, load dist as an unpacked extension in a browser and try the shortcut, and open a pull request that lists the commands and their default keys.",
  "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 changes `public/manifest.json`, `src/background.ts`, `src/popup.tsx`, `src/content_script.tsx` and `src/options.tsx`, and adds `src/messages.ts` with two test files under `src/__tests__/`. The description lists each command, its description string and its suggested keys per platform, and quotes the build and Jest summaries.

The transcript holds the `npm ci`, the webpack build with the chunk list, the Jest run, and the browser session where the agent loaded `dist/` unpacked and pressed the shortcut, with a screenshot of the page before and after, so a reviewer sees the command reach the content script rather than reading that it should. The repository's `build` workflow runs the same install, build and tests on the pull request.

Before merging, a reviewer checks that the manifest's suggested keys do not collide with Chrome's own bindings, that the listener ignores a command it does not know, that the options page copes with an unassigned shortcut, and that the content script restores the original background rather than a hard-coded colour. A follow-up message to the same session adds a third command or a per-site toggle stored in `chrome.storage.sync`, and the sandbox already has `node_modules` and the browser.

## Run it on every Linear issue labelled agent

In the Project that holds the extension, add an automation with this prompt and a `linear` trigger on `linear.issue.labeled` filtered to the `agent` label. Each labelled extension issue starts its own run in its own sandbox and ends in its own pull request; the issue text follows the prompt as data, and the trigger fills in no placeholder.

A handler on your own server does the same without the automation: it receives Linear's webhook, puts the issue text into `input`, and sends `POST /o/{org}/sessions` with the repository in `resources` and a `request_id` that is a UUID v5 of the issue id, so a redelivered webhook returns the run already started.

## Why run it on Rush?

Extension work is checked by loading `dist/` unpacked, reloading after each build and pressing keys in a real page, and the service worker's logs live in a separate inspector. In a Rush sandbox the agent has Node, the webpack build and a Chromium it can drive, loads the extension itself, presses the shortcut and keeps the screenshots and the worker's output in the record.

Small extension requests pile up because each one costs a build-and-reload cycle on someone's machine. Labelling the issue hands that cycle to a sandbox, and the pull request arrives with the build, the tests and a browser check already done. Several extensions get the same treatment at once, each in its own sandbox.

## Frequently asked questions

### Can users change the keys?

Yes. Chrome lets users rebind any extension command at `chrome://extensions/shortcuts`, and the options page the agent writes links there and shows the current binding from `chrome.commands.getAll`, so a user sees what is bound after changing it.

### What happens if my suggested key is already taken?

Chrome leaves the command unassigned rather than overriding another extension or its own binding. The options page shows it as unassigned with the link to bind it. The agent picks defaults that Chrome's documentation does not reserve, and the pull request lists them so a reviewer can change them.

### Does the shortcut work when the popup is closed?

Yes. `chrome.commands.onCommand` fires in the service worker, which Chrome wakes for the event, so `toggle-background` works with no popup open. `_execute_action` is handled by Chrome itself and opens the popup.

### How is the service worker tested without Chrome?

The command listener is a function registered on `chrome.commands.onCommand`, so the Jest test installs a stubbed `chrome` global, captures the listener and calls it with `toggle-background`, then asserts that `chrome.tabs.sendMessage` was called with the shared message. The browser check in the sandbox covers the real wiring.

## More Chrome Extension jobs

- [Add Desktop Notifications to a Chrome Extension](https://getrush.ai/run/add-notifications/chrome-extension/)
- [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/)

## The same job on other stacks

- [Add Keyboard Shortcuts to an Electron App from a Linear Issue](https://getrush.ai/run/add-keyboard-shortcuts/electron/)

## More jobs like this: Turn a Linear label into a PR

- [Add KV Caching to a Cloudflare Worker](https://getrush.ai/run/add-kv-caching/cloudflare-workers/)
- [Add Lambda Powertools to an AWS CDK App from a Linear Issue](https://getrush.ai/run/add-lambda-powertools/aws-cdk/)

## 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/)
