Plugin settings

macotron.plugin() describes a plugin to Settings: its name, what it does, the permissions it needs, and the options a user can change. It returns the current option values.

const opts = macotron.plugin({
  title: "Chat",
  description: "Talk to a model",
  help: "Set an API key below for cloud models.",
  permissions: ["accessibility"],
  options: {
    model: {
      type: "dropdown", label: "Model", default: "sonnet",
      choices: [
        { value: "sonnet", label: "Claude Sonnet" },
        { value: "opus", label: "Claude Opus" },
      ],
    },
    apiKey: { type: "password", label: "Anthropic API key", required: true },
    openHotkey: { type: "keybinding", label: "Open chat", default: "cmd+shift+c" },
  },
});

console.log("chat: model =", opts.model);

Metadata

Field	What it does
`title`	The plugin's name in Settings → Plugins and the catalog.
`description`	One sentence under the title.
`help`	Extra explanation on the plugin's Settings page.
`permissions`	The macOS permissions the plugin needs. See below.
`options`	Settings the user can change. See below.

Put the call at the top of the file and write title and description as plain string literals. Settings reads them from the first part of the file without running it, so it can show a plugin that is disabled or still waiting for approval.

Permissions

List what the plugin needs, and Macotron adds those permissions to the Permissions tab and to the plugin's own page:

Name	Needed for
`accessibility`	Moving and focusing windows, reading other apps' UI
`inputMonitoring`	Watching keys, mouse, and trackpad gestures
`screenRecording`	Capturing the screen
`camera`	The camera, such as scanning a QR code
`microphone`	Recording audio
`calendar`	Reading calendar events
`helper`	Privileged work through the background helper, such as fan control

A declaration is a request, not a sandbox. Macotron cannot limit a plugin to what it declared. Permissions explains each one.

Options

Each key in options becomes a row on the plugin's page in Settings → Plugins. The user edits the value there, and macotron.plugin() returns it under the same key. Changing a value reloads plugins, so the plugin reads the new value at load.

Type	Control in Settings	Value
`string`	Text field	String
`text`	Multi-line text area	String
`boolean`	Checkbox	Boolean
`number`	Number field, or a slider when `min` and `max` are both set	Number
`dropdown`	Pop-up menu from `choices: [{ value, label }]`	The chosen `value`
`keybinding`	Shortcut recorder	A combo such as `"cmd+shift+c"`
`password`	Secure field with Set and Clear	The secret, or `""`
`file`	Choose… button for a file	Absolute path
`directory`	Choose… button for a folder	Absolute path
`calendars`	A checkbox for each of the user's calendars	Array of calendar names; needs Calendars access first

Every option takes these fields:

label: a few words. It is required.
default: the value before the user changes it. password has no default.
required: when true, Settings marks the field Required and lists it first.
help: a sentence under the field. Put the explanation here and keep the label short.

Text, number, password, file, and directory options also take placeholder, the grey hint shown while the field is empty. It is read at load, so it can show live state:

locale: { type: "string", label: "Locale", placeholder: macotron.system.locale().language },

A number option with min and max also takes step.

Secrets

A password option keeps its value in the macOS Keychain. settings.json stores only a reference to the Keychain item, so the file is safe to commit. macotron.plugin() returns the secret itself. Never write a key into plugin source or settings.json.

Checks

A plugin can report a problem it found, such as a blocked system feature, with macotron.checks(). A failed check puts an orange warning on the plugin in Settings → Plugins and a row in its Checks section. Each call replaces the list, and [] clears it.

macotron.checks([
  { title: "Speed control", ok: false, message: "This Mac blocked fan-speed writes." },
]);

macotron.settings.open() opens the plugin's own page in Settings.

The plugin page

Each plugin's page in Settings → Plugins shows, where they apply:

Enabled: a disabled plugin stays on disk but does not load.
Permissions: what the header declared, and whether each is granted.
Menu Bar: items macOS is not showing, with Restore.
Checks: from macotron.checks().
Listens for: the events the plugin handles.
Shortcuts and Commands: hotkeys and launcher commands, each with a recorder to change or assign a key.
Settings: the options above.
Open Source File and Delete…. Delete keeps a copy in the workdir's backups/ folder.