Package Format & Directory Schema

Authoritative reference: the current manifest schema, all action kinds, options, requirements, groups, and the runtime result surface are documented in Extensions/AGENTS.md. This page is a summary and may lag it.

OpenClip extension packages are directory bundles (suffixed with .openclipext or plain directories) containing a manifest JSON file (manifest.json, openclip.json, or Config.json) along with supporting script files and local asset icons.

Package Directory Structure#

my-extension.openclipext/
├── manifest.json # Required: Extension manifest definition
├── main.js # Action script file (JavaScript, AppleScript, or Executable)
├── icon.png # Optional: Local action icon image
└── README.md # Optional: Documentation

Installation#

• Finder Double-Click: .openclipext bundles are registered macOS document packages owned by OpenClip (com.openclip.extension). Double-clicking a .openclipext package (or .openclipext.zip archive) opens a confirmation dialog in OpenClip with package metadata, installs the package directly into ~/.openclip/extensions, and marks it trusted.
• Extension Store: Deep links (openclip://install?id=...&url=...) download and install verified releases.
• Manual / CLI: Drop folders into ~/.openclip/extensions or run ./Extensions/scripts/install.sh <path>.

Manifest JSON Schema (ExtensionMetadata)#

OpenClip decodes extension metadata via ExtensionMetadata. To ensure backward compatibility, the decoder supports both modern camelCase keys and legacy capitalized/singular keys.

Complete Example manifest.json#

{
 "identifier": "com.example.jsonformatter",
 "name": "JSON & Text Utilities",
 "actions": [
 {
 "id": "com.example.jsonformatter.prettify",
 "title": "Prettify JSON",
 "icon": "symbol:doc.plaintext",
 "type": "javascript",
 "script": "main.js"
 },
 {
 "id": "com.example.jsonformatter.docs",
 "title": "Search JSON Docs",
 "icon": "symbol:magnifyingglass",
 "url": "https://developer.mozilla.org/en-US/search?q={query}"
 }
 ],
 "options": [
 {
 "identifier": "indent_spaces",
 "label": "Indentation Spaces",
 "type": "string",
 "default": "2"
 }
 ]
}

Manifest Fields Reference#

Top-Level Metadata (ExtensionMetadata)#

Manifests are validated on load (ManifestValidator): unknown action kinds, missing required fields (keyPress/shortcutName/subActions/executable payload), and any declared capability reject the package, which is then logged (category extensions) rather than silently skipped. See docs/architecture/extensions.md.

Action Object (ExtensionActionMetadata)#

text accepts nonblank selection, clipboard, or OCR text. liveSelection requires text from the current live selection. editableSelection additionally requires confirmed editability of that selection; unknown editability fails closed. Paste destination support is independent from input source, so clipboard-derived transformations can still be pasted into a confirmed destination. Older OpenClip releases ignore unknown manifest keys; do not publish catalog packages that rely on these gates until an enforcing release exists. The current source version 1.7.3 is not a confirmed compatibility floor, so minOpenClipVersion must wait for that release's version to be established.

The secondary/toast/secondaryToast keys map onto the per-action Action.delivery (see Extensions/AGENTS.md §5b); the delivery decision (Select → Probe → Toast) then applies the probe and resolves the companion toast.

Extension Output Contract & Delivery Resolution#

OpenClip uses an Author Output Contract system (output and result) for extensions:

• output (text | file | none | dynamic): Declares what type of output the action produces. Non-output actions (url, keyPress, shortcut, service) default to none.
• result (preview | paste | copy | paste-or-copy | open | save): Declares the author's recommended default outcome. Text actions default to paste-or-copy; file actions default to preview.
• User Customization: Users can override the delivery mode per-action in Settings (Show in card, Paste, Copy).
• Clipboard Invariant: Secondary click (right-click or ⇧-click) always copies the result to the clipboard (or displays a preview card if the primary click was copy), unless the action explicitly declares a custom secondary outcome.

Native File Output Results#

Actions implemented in JavaScript (openclip.file, openclip.copyFile, openclip.saveFile) or executable scripts (JSON {"type": "file" | "copyFile" | "saveFile", ...} or auto-detected regular file paths on stdout) can produce native file results. When returning a file, OpenClip renders an interactive file preview card in the popup panel (supporting inline image/SVG previews, system file icons, metadata inspection, drag-and-drop into other apps, and Open/Copy/Save shortcuts) or triggers direct clipboard copy / disk saving.

type: "canvas" (removed)#

The former interactive-canvas kind "canvas" was removed; a type: "canvas" manifest is rejected at load (unknownActionKind("canvas")).

Options Schema (ExtensionOptionMetadata)#

Extensions can expose user preferences rendered in the Preferences window under Dynamic Action Configuration.

Option Storage & Retrieval#

• Non-secret option values are saved through SettingsStore using typed setting key strings: SettingKey<String>("action.<id>.option.<identifier>", defaultValue:).
• type: "secret" option values live in SecretStore (~/.openclip/secrets.json with POSIX 0600 permissions), never SettingsStore/UserDefaults — resolved via SecretActionOptionStore.
• Direct UserDefaults.standard access is discouraged and should not be added in new code. The JavaScript runtime reads options through the injected ActionOptionReading store (OpenClipJSHost), not UserDefaults.

Native result shapes and migration from retired requirements.expression are documented in native content requirements.