Manifest Specification (openclip.json)
Extension AuthoringManifest Specification (openclip.json)

Manifest Specification (openclip.json)

The authoritative schema reference for openclip.json and .openclipext packages.

Agent Prompt

Copy instruction prompt for Cursor, Claude, Antigravity, or ChatGPT.

OpenClip extensions are directory bundles (named <name>.openclipext) containing an openclip.json manifest file, optional script files, and local image assets.

Package Structure

Directory Layout
~/.openclip/extensions/
└── word-counter.openclipext/
    ├── openclip.json       # Manifest configuration
    ├── index.js            # JavaScript script
    └── icon.png            # Optional icon

Root Manifest Schema

openclip.json
{
  // REQUIRED: Unique reverse-DNS identifier (namespace for all actions)
  "identifier": "com.example.wordtools",

  // REQUIRED: Human-readable display name
  "name": "Word Tools",

  // OPTIONAL: Semantic version string
  "version": "1.0.0",

  // OPTIONAL: Must be empty [] (non-empty rejects manifest at load time)
  "capabilities": [],

  // REQUIRED: Array of actions or single action object
  "actions": [
    {
      "id": "count",
      "title": "Word Count",
      "type": "javascript",
      "script": "index.js",
      "icon": "symbol(number)"
    }
  ],

  // OPTIONAL: Shared package-level options
  "options": []
}

Uniform Action-ID Rule

Every action is assigned a globally unique identifier via ExtensionManager.uniformActionID:

  • Explicit ID with dot: "com.custom.action" → used verbatim.
  • Bare slug without dot: "count" → prefixed as "com.example.wordtools.count".
  • Omitted ID: Indexed automatically as "com.example.wordtools.action.0".

Action Metadata Schema

FieldTypeDescription
idStringAction ID. Follows Uniform Action-ID Rule.
titleStringMenu display title (defaults to manifest name).
iconStringSF Symbol or relative asset path (see Icon Syntax).
typeStringAction kind: "url", "javascript", "applescript", "shell", "textsnippet", "keypress", "shortcut", "service", "group".
urlStringURL template containing placeholders ({query}, {text}).
scriptStringRelative path to script file (main.js, script.sh, run.applescript).
scriptCodeStringInline source code string.
requirementsObjectDeclarative visibility & enablement gates.
optionsArrayAction-specific option definitions.
afterStringPost-action outcome: "copy-result", "paste-result", "none", "default".
asyncBooleanEnables async execution & native fetch in JavaScript actions.
loadingBooleanCloses popup immediately and shows a loading spinner toast.
loadingMessageStringCustom loading spinner toast message (default: "Opening <title>…").

Icon Resolution Syntax

  • SF Symbols explicit: "symbol(wand.and.stars)" or "symbol(character.cursor.ibeam)"
  • Bare SF Symbol: "magnifyingglass" or "scissors"
  • Local Package Asset: File paths ending in .png, .jpg, .svg, .icns, .gif (e.g. "icon.png")
  • Fallback: Defaults to symbol(wand.and.stars) if omitted.

Configurable Options & Keychain

openclip.json (Options)
"options": [
  {
    "identifier": "apiKey",
    "label": "API Key",
    "type": "secret",       // Securely stored in macOS Keychain
    "default": ""
  },
  {
    "identifier": "format",
    "label": "Output Format",
    "type": "multiple",     // Dropdown picker in Preferences
    "default": "json",
    "values": ["json", "xml", "csv"]
  },
  {
    "identifier": "minify",
    "label": "Minify Output",
    "type": "boolean",      // Checkbox toggle
    "default": "false"
  }
]

Automatic Keychain Protection

Options declared with "type": "secret" are stored exclusively in the macOS Keychain under com.openclip.action-options. They are never written to UserDefaults or cached unencrypted on disk.