tampermonkey

# 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
// ==UserScript==
// @name         My Script Name                    // ← CUSTOMISE: Unique script name
// @namespace    https://example.com/scripts/      // ← CUSTOMISE: Your unique namespace
// @version      1.0.0                             // ← INCREMENT on updates
// @description  Brief description of the script   // ← CUSTOMISE: What it does
// @author       Your Name                         // ← CUSTOMISE: Your name
// @match        https://example.com/*             // ← CUSTOMISE: Target URL pattern
// @grant        none                              // ← ADD permissions as needed
// @run-at       document-idle                     // ← ADJUST timing if needed
// ==/UserScript==

(function() {
    'use strict';

    // Your code here
    console.log('Script loaded!');
})();
```

---

## 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` |

**For complete header documentation, see:** [header-reference.md](references/header-reference.md)

---

## URL Matching Quick Reference

```javascript
// Exact domain
// @match https://example.com/*

// All subdomains
// @mat