Extending OpenClip Overview

Start here: the self-contained authoring guide is Extensions/AGENTS.md (manifest schema, all action kinds, options/requirements, groups, and the result surface). This page is a high-level orientation.

OpenClip provides a pluggable extension architecture that allows developers and power users to create custom text manipulation tools, integrate third-party APIs, and automate macOS workflows.

Extension Capabilities#

You can extend OpenClip in three distinct ways:

Extending OpenClip
├── 1. Custom Actions (GUI-configured)
│ ├── Web URL search templates
│ └── Inline shell scripts (bash, zsh, python, node)
│
├── 2. Standalone Script Snippets (Header Metadata)
│ ├── Single file scripts (.sh, .py, .js, .applescript)
│ └── Header comments declaring title, icon, and options
│
└── 3. OpenClip Extension Packages (.openclipext)
 ├── Directory containing manifest.json / openclip.json
 ├── Support for JavaScript (JSContext), AppleScript (NSAppleScript), and Executables
 └── Custom options UI schema (strings, booleans, dropdowns)

Action Types at a Glance#

Extension Directory Locations#

OpenClip automatically scans the following directory for extensions and script files at launch:

~/.openclip/extensions/
├── my-extension.openclipext/
│ ├── manifest.json
│ ├── main.js
│ └── icon.png
├── currency-converter.py
└── format-sql.sh

Architectural Integration Seam#

Extending OpenClip does not require modifying Core framework code:

1. When extensions are placed in ~/.openclip/extensions/, ExtensionManager automatically parses manifests and snippets.
2. Extension metadata is passed to DefaultActionFactory (the Action Factory).
3. Derived action instances are registered with ActionRegistry through ActionCoordinator.