| name | tampermonkey |
| description | Write and debug Tampermonkey userscripts for browser automation, page modification, and web enhancement. Use whenever the user mentions userscripts, Tampermonkey, Greasemonkey, Violentmonkey, or wants to write a script that runs on a website - even if they don't say 'userscript' explicitly. Also trigger for: injecting JavaScript or CSS into web pages, modifying website behaviour, hiding page elements, form auto-fill, scraping page data, intercepting requests, detecting URL changes in SPAs, adding keyboard shortcuts to websites, tab audio control, or TypeScript userscripts. Covers all header tags (@match, @grant, @require, @run-in), GM_* synchronous APIs, GM.* promise-based APIs (recommended for new scripts), batch storage (GM.getValues/setValues v5.3+), binary data support (v5.4+), TypeScript setup via @types/tampermonkey, security sandboxing, and cross-browser compatibility (Chrome, Firefox, Edge). Do NOT use for Selenium/Puppeteer automation, browser extensions (WebExtensions/MV3), or server-side scripts. |
| allowed-tools | Read, Glob, Grep, Write, Edit |
Tampermonkey Userscript Development
Expert guidance for writing Tampermonkey userscripts - browser scripts that modify web pages, automate tasks, and enhance browsing experience.
Quick Start Template
JavaScript (simple scripts with no GM. APIs)*
(function() {
'use strict';
})();
Modern (async/await - recommended when using GM. APIs)*
(async () => {
'use strict';
const setting = await GM.getValue('myKey', 'default');
console.log('Script loaded, setting:', setting);
})();
TypeScript: Add @types/tampermonkey for full type safety. See typescript.md.
Essential Header Tags
| Tag | Required | Purpose | Example |
|---|
@name | Yes | Script name (supports i18n with :locale) | @name My Script |
@namespace | Recommended | Unique identifier namespace | @namespace https://yoursite.com/ |
@version | Yes* | Version for updates (*required for auto-update) | @version 1.2.3 |
@description | Recommended | What the script does | @description Enhances page layout |
@match | Yes** | URLs to run on (**or @include) | @match https://example.com/* |
@grant | Situational | API permissions (use none for no GM_* APIs) | @grant GM_setValue |
@run-at | Optional | When to inject (default: document-idle) | @run-at document-start |
@run-in | Optional | Limit to normal or incognito tabs, or Firefox containers (v5.3+) | @run-in normal-tabs |
For complete header documentation, see: header-reference.md
URL Matching Quick Reference
For advanced patterns (regex, @include, specific paths), see: url-matching.md
@grant Permissions Quick Reference
| You Need To... | Grant This |
|---|
| Store persistent data | @grant GM_setValue + @grant GM_getValue |
| Make cross-origin requests | @grant GM_xmlhttpRequest + @connect domain |
| Add custom CSS | @grant GM_addStyle |
| Access page's window | @grant unsafeWindow |
| Show notifications | @grant GM_notification |
| Add menu commands | @grant GM_registerMenuCommand |
| Detect URL changes (SPA) | @grant window.onurlchange |
| Batch read/write settings (v5.3+) | @grant GM.getValues + @grant GM.setValues |
| Mute/unmute tab audio | @grant GM_audio |
For complete permissions guide, see: header-reference.md
@run-at Injection Timing
| Value | When Script Runs | Use Case |
|---|
document-start | Before DOM exists | Block resources, modify globals early |
document-body | When body exists | Early DOM manipulation |
document-end | At DOMContentLoaded | Most scripts - DOM ready |
document-idle | After DOMContentLoaded (default) | Safe default |
context-menu | On right-click menu | User-triggered actions |
Common Patterns
These patterns are used frequently. Brief summaries are below - load patterns.md for full implementations with code examples.
- Wait for Element - Promise-based MutationObserver that resolves when a CSS selector appears in the DOM, with configurable timeout
- SPA URL Change Detection - Detect navigation in single-page apps using
window.onurlchange grant or History API interception
- Cross-Origin Request - Fetch data from external APIs using
GM_xmlhttpRequest with @connect domain whitelisting. See also http-requests.md
- Add Custom Styles - Inject CSS with
GM_addStyle to restyle pages or hide elements. See also api-dom-ui.md
- Persistent Settings - Store user preferences with
GM_setValue/GM_getValue and expose toggle via GM_registerMenuCommand. See also api-storage.md
- DOM Mutation Observation - Watch for dynamically added content with MutationObserver (debounced variant included)
- Element Manipulation - Inject HTML, remove/hide elements, replace text across the page
- Keyboard Shortcuts - Simple handlers and a shortcut manager with modifier key support
- Data Extraction - Extract table data to arrays/objects, collect and filter page links
- Error Handling - Safe wrapper for try/catch and async retry with exponential backoff
- TypeScript Userscripts - Type-safe scripts with
@types/tampermonkey. See typescript.md
External Resources
TypeScript Support
Install the type definitions for full IDE autocompletion and type safety:
npm install --save-dev @types/tampermonkey
(async () => {
'use strict';
const value = await GM.getValue<string>('key', 'default');
const info: Tampermonkey.ScriptInfo = GM_info;
console.log(info.script.name, value);
})();
Build with a bundler (esbuild, Vite, webpack) to a single .user.js output file. For full project setup including tsconfig and bundler config, see typescript.md.
What Tampermonkey Cannot Do
Userscripts have limitations:
- Access local files - Cannot read/write files on your computer
- Run before page scripts - In isolated sandbox mode, page scripts run first
- Access cross-origin iframes - Browser security prevents this
- Persist across machines - GM storage is local to each browser
- Bypass all CSP - Some very strict CSP cannot be bypassed
- Inject without permission - Tampermonkey v5.4.1+ requires users to grant injection permission per-site or globally; scripts cannot bypass this requirement
Most limitations have workarounds - see common-pitfalls.md.
When Generating Userscripts
Always include in your response:
- Explanation - What the script does (1-2 sentences)
- Complete userscript - Full code with all headers in a code block
- Installation - "Copy/paste into Tampermonkey dashboard" or "Save as .user.js"
- Customisation points - What the user can safely modify (selectors, timeouts, etc.)
- Permissions used - Which @grants and why they're needed
- Browser support - If Chrome-only, Firefox-only, or universal
Pre-Delivery Checklist
Before returning a userscript, verify:
Critical (Must Pass)
Important (Should Pass)
Recommended
For complete security checklist, see: security-checklist.md
Reference Files Guide
Load these on-demand based on user needs:
