userscripts #
Browser userscripts — Tampermonkey/Violentmonkey-installable scripts that enhance sites I use online. Userscripts-first (MediaWiki + general web), with room to broaden into bookmarklets, console snippets, and per-site tooling.
Private collection. Authored/iterated with Claude; the layout is designed so work-in-progress is cheap to start and promotion to a stable, installable script is explicit.
Layout #
| Dir | Holds | Promotes to |
|---|---|---|
drafts/ |
WIP scripts being shaped — may be broken, half-ideas, spikes | scripts/ once it works and has a proper metadata header |
scripts/ |
The real deal: installable *.user.js with full ==UserScript== headers |
— (this is the shippable layer) |
samples/ |
Reference scripts (mine or others') kept to learn from — not meant to be installed as-is | — (study material) |
memory/ |
Notes: per-site quirks, DOM selectors that break, API gotchas, decisions | — (knowledge, not code) |
mw/ |
MediaWiki-sourced scripts/gadgets tracked with mwsync — the registry/recipe (e.g. Navigation popups); fetch bodies on demand (cache is gitignored) | — (recipe) |
A script lives in exactly one of drafts/ or scripts/. The move between them
is the "is this real yet?" boundary — same spirit as the seedbed→transplant
lifecycle one level up.
Conventions #
- Filenames:
<site-or-purpose>.user.js(e.g.mediawiki-edit-shortcuts.user.js). The.user.jssuffix is what makes Tampermonkey offer to install on click. - Metadata header: every script in
scripts/carries a complete==UserScript==block —@name,@namespace,@version(semver),@description,@match/@include,@grant, and update URLs (see below). Start fromscripts/TEMPLATE.user.js. - Versioning: bump
@versionon every behavioral change. The header version is the source of truth for update reporting. - One concern per script (Unix-y). Compose, don't kitchen-sink.
Roadmap — management & distribution #
The collection is step one; the goal is a small userscript manager layer around it. Tracked here so the structure anticipates it (specs land alongside code when each is built):
- Tampermonkey-ready hosting. Serve raw
scripts/*.user.jsover a stable URL (raw.githubusercontent / GH Pages / a tiny proxy) so install + auto-update work. Each script's@updateURL(metadata-only.meta.js) and@downloadURLpoint back here → Tampermonkey reports "update available" natively. - Pinning by hash. Record a content hash (sha256) per published version in a lockfile/manifest so an install can be pinned to a known-good revision and drift is detectable — supply-chain hygiene for self-hosted scripts.
- Update-available reporting. A manifest (
scripts/manifest.json?) listing name / version / hash / match-globs, so a glance — or a checker script — shows what's outdated across installs without opening Tampermonkey. - Version manager + enable toggler. A control surface (CLI and/or a meta userscript) to list installed scripts, their versions vs. latest, and enable/disable individually — the "version manager and enable toggler" goal.
- State opportunities. Where scripts touch
localStorage/ cookies /GM_setValue, document the keys and surface them (inspect / export / reset). Cookies likely don't matter for most;localStorage+GM_*storage do. - CDN delivery + SRI + version-tracking. jsDelivr GitHub passthrough for
in-page
<script>loading, SRI hashes for verified pins, and an in-script metadata block (Tampermonkey- / PEP-723-style) that tracks upstreams and suggests the diff to bump a pinned wikicommon.js/ Tampermonkey inclusion. Detailed inmw/README.md. - On-page notification library. Reusable, unobtrusive in-page toasts/banners
for scripts to report status, updates, and prompts — one shared surface rather
than each script reinventing
alert(). - Storage/environment probing library. Scripts that probe and characterize
what an origin offers — cookies,
localStorage,sessionStorage, IndexedDB,GM_*— for capacity, context, and preference persistence. Goal: durable reuse within an origin (or its primary origin).
These are intent, not yet built. Each gets a spec alongside its first commit.
Status #
See STATUS.md for current state and next steps.
Provenance #
Born as a standalone repo (not via the usual seedbed→transplant path) because
hosted-git is a day-one requirement here: Tampermonkey install/auto-update and
the claude.ai GitHub-connector loop both want a real remote. Sibling in spirit
to the claude-ai-workspace seed in the seedbed (a git-backed tree shared with
claude.ai).