gemma4-browser-extension: an on-device agent that drives Chrome through four tool families
On-device AI agent Chrome extension powered by Transformers.js and Gemma 4
At a glance
- What is it?
- A Chrome extension that runs Gemma 4 in the browser via Transformers.js and WebGPU, exposing tab control, page RAG and a semantic history index as agent tools. The architecture is the interesting part; the hardware requirement is the catch.
- Who is it for?
- Adopt it if you have a WebGPU-capable GPU and want a working reference for hosting Transformers.js models in a background service worker while content scripts handle DOM work. Do not adopt it if you need a supported product, a Firefox or Safari build, or a machine without a discrete or modern integrated GPU, because the model download and the WebGPU prerequisite are both hard gates.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 33 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap between a chat sidebar and a browser that actually does something
Most browser AI extensions are a text box wired to a remote endpoint. They can talk about the page you are looking at, but they cannot switch tabs, they cannot scroll to a paragraph, and every query leaves the machine. This project takes the other position: the model runs locally and the agent is given tools that mutate browser state. The README lists four tool families. Tab management covers get_open_tabs, go_to_tab, open_url and close_tab. Website interaction covers ask_website and highlight_website_element. History search covers find_history. The intended user is someone who wants natural-language control over Chrome without shipping browsing data to a vendor, and who is willing to accept a one-time multi-gigabyte model download in exchange. It is a developer-facing project rather than a packaged product: there are no releases retrieved, and installation is a clone, a build and a Load unpacked step.
Three contexts, one model, and why the split is not cosmetic
The architecture divides work across a background service worker, a side panel and per-tab content scripts, and the README explains each choice. The background worker hosts the Transformers.js models, so they are loaded once and shared across every tab and panel instead of being re-instantiated per surface. The README also notes that service workers can stay alive during active ML processing, which matters because inference may take several seconds. The side panel is React and keeps conversation state across the browsing session, unlike a popup that closes when focus moves. Content scripts are the only component with DOM access, so extraction and highlighting live there. The message flow is explicit: side panel to background via chrome.runtime.sendMessage, background to content script via chrome.tabs.sendMessage, response back through the same pair. That is a sound arrangement, and it is the part of this repository most worth reading even if you never install it.
RAG over the current page, and what the embeddings are for
ask_website is not a full-text dump into the prompt. According to the README, the content script extracts structured content (headings, paragraphs, lists), generates embeddings with all-MiniLM-L6-v2, and returns the most relevant sections for the query. So there are two models in play: a small sentence embedding model for retrieval and Gemma 4 for generation. highlight_website_element then scrolls to and marks the element the agent selected, which closes the loop between a text answer and a visual location on the page. The same embedding machinery backs find_history, which stores vectors for page titles, descriptions and URLs in IndexedDB and supports time-based filtering. That is a meaningful design decision: history search becomes semantic rather than substring matching, and the index lives in the browser profile rather than on a server. It also means the history index is only as good as the descriptions Chrome exposes for visited pages.
Getting it running: clone, pnpm, build, load unpacked
The documented path is short. Clone the repository and cd into tfjs-agentgemma-extension, then run pnpm install and pnpm run build. In Chrome, open chrome://extensions/, enable Developer mode, click Load unpacked and select the dist folder. For iteration there is pnpm run dev, described as rebuilding automatically. The stated prerequisites are Chrome 113 or later with WebGPU support and a modern GPU with WebGPU capabilities. On first use the models download automatically, which the README calls a one-time cost. The permission set is worth reading before you build: sidePanel, activeTab, storage, scripting, tabs, and host_permissions granting access to webpage content on all URLs. That last one is the widest grant in the manifest and it is required because the content script has to read arbitrary pages for RAG. If your threat model does not accept an extension that can read every page you visit, this is the line that decides it.
Where it breaks: WebGPU, model weight, and the all-URLs grant
The constraints here are hardware and network, not bugs. WebGPU availability is a prerequisite the README states plainly, and on machines without it the extension has no fallback path described. The model is onnx-community/gemma-4-E2B-it-ONNX, an instruction-tuned ONNX build; the README describes the models as multi-gigabyte when explaining why they are loaded once in the background worker. First run therefore costs a large download before the agent can answer anything, and that download is a hard dependency on the Hugging Face host being reachable. There is also a subtler failure mode in the RAG path: ask_website depends on the content script having extracted structured content from the current page. Pages that render their text client-side, or that are mostly canvas or video, give the extractor little to work with, and the README does not describe a fallback for that case. Finally, the project has no releases retrieved and no homepage, so there is no versioned artifact to pin against. You are tracking main.
Compared with a server-side agent or a plain summarizer extension
The obvious alternative is a hosted agent that calls a frontier model through an API and drives the browser with the same tool schema. That approach removes the WebGPU requirement and the multi-gigabyte download entirely, and it will generally produce better answers, because the model is larger than anything you can run in a tab. The difference in approach is where the data goes: this project keeps page content, embeddings and history vectors on the device, with the history index in IndexedDB and inference in the service worker. If your reason for wanting an agent is privacy or offline use, the hosted route fails on the first criterion and this one fails on hardware. A second alternative is a conventional summarizer extension that sends the current page to a model and returns text. That is cheaper and simpler, but it cannot call close_tab or go_to_tab, so it does not control the browser at all. The tool-calling design is what separates this project from that class of extension.
Maintenance surface and the MIT licence
The licence is MIT, which permits reuse and modification with the copyright notice retained; that is the extent of what can be said here without giving legal advice, and anyone redistributing a build should read the full text themselves. The practical maintenance cost sits in three places. First, the model reference: the extension points at a specific Hugging Face repository, so a change or removal upstream is a change you inherit. Second, the Chrome platform: WebGPU support and service worker lifetime behaviour are browser-controlled, and the README's argument for hosting models in the background worker rests on the assumption that the worker stays alive during inference. Third, the build: a pnpm-based TypeScript project with no published releases means upgrades are git pulls against main, with no changelog to read between them. For a team, that is a small amount of ongoing work, but it is not zero, and it is concentrated in dependency and platform churn rather than in application code.
Editorial conclusion
Adopt it if you have a WebGPU-capable GPU and want a working reference for hosting Transformers.js models in a background service worker while content scripts handle DOM work. Do not adopt it if you need a supported product, a Firefox or Safari build, or a machine without a discrete or modern integrated GPU, because the model download and the WebGPU prerequisite are both hard gates. Before committing, verify three things in your own checkout: that Chrome reports WebGPU available, that the onnx-community/gemma-4-E2B-it-ONNX download completes on your connection, and that the host_permissions entry covering all URLs is something you can accept for the sites your team browses.
Community notes