Monitoring Tools

Clipboard

Extensions

Extensions teach the clipboard new tricks. Each one is a small folder with a description of what to notice and a program to run when you press one of its buttons.

The extensions manager

#Manage extensions

  1. Open the command palette (Ctrl+Shift+F) and choose Extensions.
  2. The list shows every extension in your extensions folder. Choose one to see what it notices, the buttons it adds, what it may do and its last runs.
  3. Use the switch to turn it on or off. Turning one on shows exactly what it asks for; press Allow and turn on.
  4. Add an extension (Ctrl+N) copies an extension folder in. Open the folder (Ctrl+O) opens %LOCALAPPDATA%\MonitoringTools\Extensions. More has Reload all (F5), the author guide and Turn every extension off.

New extensions start off. If an extension's version or permissions change, it turns off until you allow it again.

Allowing an extension

#Built-in extensions

The app comes with eleven extensions, written in PowerShell so they run on every Windows PC. They are installed the first time the app starts and start on. Copy what the first column shows, then press the button on the toast.

ExtensionNoticesButton and result
Case stylesNames in code: userName, user_name, user-name, UserNameEvery case style: camelCase, PascalCase, snake_case, SCREAMING_SNAKE, kebab-case and words
HTML toolsText with entities like &, or HTML markupDecode entities, Keep only the text, Escape as text
CIDR calculatorAn IPv4 block such as 203.0.113.0/24Range and hosts: network, mask, broadcast, first and last host, usable hosts
Coordinates43.6532, -79.3832 or 43°39′11.5″N 79°22′59.5″WOpen the map on OpenStreetMap, Other formats
Roman numeralsMMXXVIAs a number
ISO durationsPT1H30M, P2DT4HIn words, with seconds and a clock
User agentsA browser user-agent stringWhat is this: browser, version, system, device
Unix permissions-rwxr-x---, chmod 644, 0755Explain: both forms and who can read, write and run
MAC addresses00:1A:2B:3C:4D:5E or 001a.2b3c.4d5eEvery format, unicast or multicast, maker prefix
Hex to textHex bytes such as 48 65 6C 6C 6FDecode to text
Morse code... --- ... / .... ..Decode Morse

The manager marks them built in. Each app update brings their newest version, but only while the folder is exactly as the app installed it: once you edit an extension it is yours and updates leave it alone. Delete a built-in extension's folder and it stays deleted. Turn any of them off with its switch; updates keep it off. A record of what was installed is kept in defaults.json in the extensions folder.

#What an extension can and cannot do

  • It only receives text that matches its own patterns, and only when you press its button.
  • It never receives copies from password managers or anything the secret guard recognises.
  • Its answer is limited to what you allowed: putting text on the clipboard, opening a web link, showing a toast or values to copy.
  • It is stopped after 5 seconds.
  • It is a program running as you, and nothing checks or signs it, so only add extensions you trust. The Use the internet permission is shown so you know about it; the app cannot block a program's own network use.

#Write an extension

An extension is a folder that holds extension.json and the program it names. Two working samples are in samples/extensions: ticket-keys (PowerShell) and morse-python (Python). The built-in extensions below are also good starting points: copy one, change its id, and edit it.

#extension.json

{
  "id": "ticket-keys",
  "name": "Ticket keys",
  "version": "1.0.0",
  "api": 1,
  "description": "Notices ticket numbers like ABC-1234 and opens them in your tracker.",
  "author": "Your name",
  "detect": [
    { "kind": "ticket", "label": "You copied a ticket number", "pattern": "^[A-Z][A-Z0-9]{1,9}-\\d{1,7}$" }
  ],
  "actions": [
    { "id": "open", "label": "Open ticket", "for": ["ticket"], "primary": true },
    { "id": "link", "label": "Copy link", "for": ["ticket"] }
  ],
  "run": "ticket-keys.ps1",
  "permissions": ["read-text", "open-links", "change-clipboard"]
}
FieldRequiredMeaning
idyes2 to 64 lower-case letters, digits or dashes. Unique.
nameyesShown in the manager and on toasts.
versionyesChanging it asks you to allow the extension again.
apiyesMust be 1.
description, authornoShown in the manager.
detectnoPatterns to notice. Each has a kind, a .NET regular expression pattern, an optional label (the toast heading) and optional flags (i, m, s). Patterns time out after 100 ms.
actionsyesButtons. Each has an id, a label, optional for (the kinds it applies to; all kinds when left out) and optional primary.
runyesThe program inside the folder. .exe starts directly, .ps1 with Windows PowerShell, .py with Python, .js with Node, .cmd and .bat with cmd.
argsnoExtra arguments for the program.
permissionssee belowWhat the extension may do.

Comments and trailing commas are allowed in extension.json.

#Permissions

PermissionAllows
read-textReceiving copied text that matches its patterns. Needed for any detect.
read-all-textPatterns that match any text. Without it, a pattern that matches an ordinary sentence is refused.
change-clipboardAnswering with copy.
open-linksAnswering with open (web links only).
internetNothing is enforced; it tells the person the program goes online.

#The protocol

When a button is pressed, the app starts the program and writes one line of JSON to its standard input:

{"api":1,"action":"open","kind":"ticket","text":"ABC-1234","extension":"ticket-keys"}

The program writes one line of JSON to standard output and exits. Every field is optional:

{"open":"https://tracker.example/browse/ABC-1234","copy":"https://tracker.example/browse/ABC-1234","toast":"Opened ABC-1234","values":[{"label":"Key","text":"ABC-1234"}]}
FieldEffect
copyPuts the text on the clipboard. Needs change-clipboard.
openOpens an http or https link. Needs open-links.
toastShows a short message (up to 300 characters).
valuesUp to 20 values shown as chips to copy.
errorShows your message as a failure.

The answer must be under 1 MB and arrive within 5 seconds. The environment variable MONITORING_TOOLS_EXTENSION_API is set to 1. Anything written to standard error is ignored.

#Try it

  1. Copy your folder into %LOCALAPPDATA%\MonitoringTools\Extensions, or use Add an extension.
  2. Turn it on and allow it.
  3. Copy something that matches a pattern. The toast shows your buttons; the last runs appear in the manager.

View this article's Markdown source on GitHub

Suggested articles

All Clipboard articles