Greasemonkey

Greasemonkey is a Mozilla Firefox extension — and, by extension, the user-script format it established — that lets a user attach small JavaScript programs to specific web pages. When a matching page loads, Greasemonkey runs the user’s script after the page’s own scripts, giving the user the power to add, remove, or rewrite arbitrary parts of the page.

Strictly speaking, Greasemonkey is not a programming language: a Greasemonkey “script” is just a JavaScript file with a structured comment header that tells the extension where and how to run it. But that header, together with a small set of GM_* helper APIs, became a de facto specification that several other extensions adopted, and the resulting “user script” format is what most people mean when they talk about Greasemonkey today.

History and Origins

Greasemonkey was created by Aaron Boodman and first released in 2004 as a Firefox extension. At the time, end-user customization of the web typically meant bookmarklets — short snippets of JavaScript stored in a browser bookmark that the user clicked to run on the current page. Greasemonkey generalized that idea: instead of clicking a bookmark each time, the user installed a script once, declared which URLs it should apply to, and let the browser run it automatically thereafter.

Within a year of release, the project had attracted enough attention to spawn O’Reilly’s Greasemonkey Hacks (2005, by Mark Pilgrim) and the userscripts.org community site. A 2005 security incident, in which early versions of the extension exposed the local file system to web pages through the same APIs that scripts used, forced a redesign of the sandboxing model and underscored that user scripts were a security-sensitive feature rather than a casual toy.

For roughly a decade, the format flourished on top of Mozilla’s old XUL/XPCOM extension system, which gave the extension privileged access to the browser. The 2017 transition to WebExtensions, the cross-browser extension model now used by Firefox and Chromium-based browsers, forced Greasemonkey to be rewritten from scratch as Greasemonkey 4.x. The rewrite preserved the user-script metadata format but removed or restricted several GM_* APIs, and the resulting incompatibility split the community: many users migrated to Tampermonkey or Violentmonkey, which retained broader compatibility with older scripts.

Design Philosophy

Greasemonkey’s design rests on a few clear ideas:

• The user is in charge of the page. Web pages are content delivered to the user’s machine; the user has the right to modify them in their own browser.
• Scripts are JavaScript. Rather than inventing a new language, Greasemonkey leans on the language already running in the browser. Anyone who can write JavaScript can write a user script.
• A small header is the API contract. The metadata block declares matching rules, required permissions, and dependencies, and changes very rarely. Most innovation happens inside the script body.
• Per-script sandboxing. Each script runs in its own isolated scope, with limited access to page globals through a controlled bridge. This both protects the page from buggy scripts and protects the user from malicious ones.
• Local-first. Scripts live on the user’s machine, run in the user’s browser, and persist data through the user’s profile.

The User-Script Format

A Greasemonkey script is a JavaScript file (.user.js) that begins with a metadata block:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// ==UserScript==
// @name         Greet on Example.com
// @namespace    https://example.com/
// @version      1.0.0
// @description  Inserts a friendly banner on example.com pages
// @match        https://example.com/*
// @grant        GM_setValue
// @grant        GM_getValue
// @run-at       document-end
// ==/UserScript==

(function () {
  'use strict';

  const banner = document.createElement('div');
  banner.textContent = 'Hello from Greasemonkey!';
  banner.style.cssText = 'padding:8px;background:#ffd;border:1px solid #cc0;';
  document.body.prepend(banner);

  const visits = (GM_getValue('visits') || 0) + 1;
  GM_setValue('visits', visits);
  console.log(`Visit number ${visits}`);
})();

Important metadata keys include:

The GM_* family of helper functions historically gave scripts capabilities the page itself could not have, such as cross-origin HTTP requests (GM_xmlhttpRequest) and persistent per-script storage (GM_setValue / GM_getValue). The WebExtensions rewrite renamed several of these to a promise-based GM.* namespace and removed some legacy variants.

Key Features

• Targeted injection. Scripts run only on pages whose URL matches their @match or @include rules, with @exclude rules for carve-outs.
• Privileged helpers. GM_xmlhttpRequest allows requests to origins the page itself could not reach; GM_setValue / GM_getValue provide per-script persistent storage independent of cookies and localStorage.
• External libraries. @require pulls in JavaScript libraries (jQuery was a common choice in the format’s heyday), letting authors write higher-level code in a small script.
• Resource bundling. @resource declarations attach static files (CSS, images, JSON) that the script can access at runtime.
• Isolated scopes. Each script gets its own global scope, preventing accidental collisions with the page or with other user scripts.

Evolution

The user-script format has stayed remarkably stable since 2004, but its surrounding world has changed considerably:

• Browser model changes. Firefox’s Quantum release in 2017 retired the XUL/XPCOM extension system, forcing a WebExtensions rewrite. Chromium’s Manifest V2 → V3 transition has imposed similar constraints on the Chrome-side ecosystems that adopted the format.
• Ecosystem competitors. Tampermonkey (2010) brought the Greasemonkey format to Chrome and later to Edge, Safari, and Opera. Violentmonkey offers an open-source alternative across browsers. Scriptish, a Firefox-only fork, attempted to extend the API but is now defunct.
• Repository churn. userscripts.org, the longtime central repository, eventually went offline. Greasy Fork, launched in 2014, has taken its place as the most-used hub for sharing scripts.
• Security and trust. As scripts gained the ability to request cross-origin data and modify any page, the user-script community has had to wrestle with the same supply-chain risks that affect any code-sharing ecosystem.

Current Relevance

Greasemonkey itself, the original Firefox extension, is still maintained and still works, but most active scripting today happens through Tampermonkey or Violentmonkey, simply because they support more browsers and a slightly larger API surface. The format, on the other hand, is healthier than ever: Greasy Fork hosts a large catalog of community scripts that target everything from major social networks to obscure corners of the web.

User scripting also continues to serve as a low-friction prototyping tool. Browser extensions require packaging, signing, and a manifest of permissions; a Greasemonkey-compatible script is a single JavaScript file that a user can copy, paste, and edit. For tinkerers, students, and people who simply want to fix a small annoyance on a site they use every day, that immediacy is the format’s enduring appeal.

Why It Matters

Greasemonkey was one of the earliest and most influential expressions of the idea that the browser belongs to its user. By letting anyone with a little JavaScript reshape the pages they visited, it predated and shaped much of the modern extension ecosystem: ad blockers, accessibility add-ons, privacy tools, and per-site tweakers all draw on the same lineage. Its metadata header — // ==UserScript== ... // ==/UserScript== — has become a small but stable piece of web culture, recognized far beyond the extension that introduced it.

For programmers, Greasemonkey is also a reminder that a “language” need not be a new syntax or a new runtime. A handful of comment conventions and a few helper APIs, bolted on top of an existing language and platform, were enough to launch an ecosystem that has outlasted browsers, extension models, and central repositories alike.