Products1 min read

Userscript runtime

Two execution engines, metadata matching, GM APIs and the permission model.

Updated Nov 6, 20251 min readEdit this page

On this page

Lumo Userscripts registers every script through the native chrome.userScripts API. There are two engines: a page-world runner and an isolated USER_SCRIPT host. Both talk to the extension over a nonce-scoped MessageChannel. The same manager optionally exposes its scripts over MCP; see Connecting an agent.

Execution model#

Engine	World	When to use it
`us-runner`	MAIN	Scripts that need the page's real `window`, or `@grant unsafeWindow`.
`us-host`	USER_SCRIPT	Scripts that should stay isolated from page globals while still using GM APIs.

@inject-into page and @grant none scripts run in the page world. USER_SCRIPT scripts get the isolated world's window; they cannot provide a synchronous page object.

Metadata#

A script headertypescript

// ==UserScript==// @name        GitHub focus mode// @namespace   https://example.com/// @version     1.4.2// @match       *://*.github.com/*// @run-at      document-idle// @grant       GM_setValue// @grant       GM_getValue// ==/UserScript==

The manager validates metadata on save, supports glob and regex rules for @match / @include / @exclude, and resolves relative @require / @resource URLs against the install source.

GM APIs#

Values: GM_setValue, GM_getValue, GM_deleteValue, GM_listValues.
Network: GM_xmlhttpRequest for cross-origin requests.
Browser: GM_cookie, GM_download, GM_notification, GM_setClipboard.
Page: GM_addStyle, GM_addElement, unsafeWindow.
Shell: GM_registerMenuCommand, tab state and the promised GM.* aliases.

Permissions#

Permission	Why it exists
`userScripts`	Dynamic registration through Chrome's native API.
`storage`, `unlimitedStorage`	Settings and bounded metadata.
`tabs`, `activeTab`, `webNavigation`, `scripting`	Tab context and diagnostics.
`declarativeNetRequest`	Redirect `.user.js` navigations to the install page.
`cookies`, `downloads`	Back `GM_cookie` and `GM_download`.
`notifications`, `contextMenus`, `alarms`, `clipboardWrite`	GM APIs and background jobs.

Updates are permission-aware

If a new version asks for more access, the update waits for the user. The manager never silently widens a script's reach.