PopClipの拡張機能を自作する方法（スニペットの作成から公開まで）

PopClipの公式ディレクトリにはさまざまな拡張機能が登録されています。

www.popclip.app

PopClip Extensions Directory

https://www.popclip.app/extensions/

翻訳やノートアプリへの取り込みといったよくありそうな機能は、だいたいここで見つかります。

しかし、自分が使っているマイナーなサービスに投げたい、社内ツールのURLを選択したIDで開きたい、といった用途では、既存の拡張機能だけで対応できないことがあります。

そんなときは、拡張機能を自作する選択肢があります。
開発者登録もビルドも要らず、テキストエディタがあれば完結します。

今回はPopClipの拡張機能を自作する方法についてまとめます。

拡張機能の2つの形式

PopClipの拡張機能には、大きく分けて「Snippets（スニペット）」と「Packages（パッケージ）」の2つの形式があります。

www.popclip.app

Snippets — PopClip Developer

https://www.popclip.app/dev/snippets

違いをまとめると下記の通りです。

Snippetsの方が気軽に追加できますが、追加ファイルの同梱や署名はできません。
配布したり自分以外も使う場合はPackagesがいいですが、自分専用や個人でのお試しレベルであればSnippetsで十分です。

まずはSnippetsで作って、配布したくなったらPackagesにする流れが良さそうです。

Snippetsで自作する

SnippetsはYAML形式のテキストを書くだけで作れます（JavaScriptで書く方法もありますが、その方法は後述します）。

最小のサンプルは下記の通りです。

#popclip
name: Urban Dictionary
icon: UD
url: https://www.urbandictionary.com/define.php?term=***

1行目の#popclipが目印で、この形式のテキストを丸ごと選択すると、PopClipが自動的に検知して「Install Extension」のアクションを表示してくれます。
***には、選択したテキストの前後の空白を取り除き、URLエンコードした値が入ります。

検索先のURLを差し替えれば、好きなサイトの検索用アクションが作れます。

そしてテキストを選択するだけで、PopClip上にインストールボタンが表示されます。

わざわざファイルを作らなくてもテキストを選択するだけで拡張機能をインストールできるという方法は、PopClipらしい仕組みで面白いです。

なお、テキスト選択からインストールできるのは5,000文字までです。
それ以上に長い場合やファイルとして保存したい場合は、.popcliptxt拡張子で保存することで、ファイルをダブルクリックでインストールできるようになります。

.yaml・.js・.tsで保存した場合は、Finderの［このアプリケーションで開く］→［PopClip］を選ぶか、PopClipのメニューバーアイコンへドラッグします。

なお、YAMLのインデントにはタブではなく半角スペースを使う必要があるので注意が必要です。

アイコンを指定する

iconで指定できる代表的な形式は、下記の通りです（アイコンの公式仕様）。

テキストアイコンはsquare（四角）やcircle（丸）といった図形の指定に、filled（塗りつぶし）を組み合わせて書きます。
icon: UDのように文字だけを書くこともできます。

バーに同じような四角が並ぶと押し間違えるので、サービスのロゴがIconifyにあるならそれを指定しておくのが分かりやすいです。

アクションの種類

指定できるアクションには、下記の6種類があります。

文字列の加工や条件分岐が必要になったら、JavaScriptやシェルスクリプトを使います。

キー入力を送る

アプリのショートカットキーを押すだけのアクションはkeyComboで書けます。

#popclip
name: Bold
icon: B
keyCombo: command b
keyComboTarget: app
stayVisible: true

command bのように、修飾キーと通常のキーを半角スペースで区切って書きます。
修飾キーはcommand・option・control・shiftが使え、cmdやoptのような省略形も通ります。

また、stayVisible: trueを付けると、クリックしてもPopClipバーが消えません。
太字と斜体を続けて当てたいときなど、連続で押したいアクションに向いています。

シェルスクリプトを実行する

シェルスクリプトを実行する場合、選択したテキストは環境変数POPCLIP_TEXTから受け取ります。

#popclip
name: Character Count
icon: symbol:textformat.123
after: show-result
interpreter: /bin/zsh
shellScript: printf '%s' "$POPCLIP_TEXT" | wc -m | tr -d ' '

POPCLIP_TEXT以外にも、ブラウザで開いているURLが入るPOPCLIP_BROWSER_URLなどが用意されています。

JavaScriptで書く

JavaScriptの場合は#popclipをコメントとして書き、その下に処理を続けます。
拡張子は.jsです。

// #popclip
// language: javascript
// name: Uppercase
// icon: square filled AB
popclip.pasteText(popclip.input.text.toUpperCase());

選択したテキストはpopclip.input.textで取得でき、popclip.pasteText()で置換できます。

上記のサンプルは選択テキストを大文字に変換していますが、このレベルの処理なら簡単に作成できます。
ちなみに、あとで説明する公式ディレクトリへの公開ではJavaScriptが推奨されています。

複数のアクションを設定する

1つの拡張機能に複数のアクションを持たせる場合はactionsに並べます。

#popclip
name: 検索
actions:
  - title: Google
    icon: iconify:simple-icons:google
    url: https://www.google.com/search?q=***
  - title: MDN
    icon: iconify:simple-icons:mdnwebdocs
    url: https://developer.mozilla.org/ja/search?q=***

titleはアイコンが無いときにボタンへ表示され、アイコンがある場合はツールチップに表示されます。

よく使う検索先を、1つの拡張機能としてまとめて管理なんてことができます。

表示条件を絞る

拡張機能を増やしていくと、バーが横に長くなって目的のアクションを探すのに時間がかかるようになってしまいます。

そこで便利な設定が「requirements」です。
選択した内容が条件に合うときだけアクションを表示する指定で、主な値は下記の通りです。

値の先頭に!を付けると条件を反転することもできます。

さらに、細かく絞りたい場合はregexで正規表現の指定も可能です。
「requirements」で絞ったあとに正規表現がかけられて、マッチした部分だけがアクションに渡ります。

例えば、選択した文字列がチケット番号のときだけ管理ツールを開く、といった書き方ができます。

#popclip
name: Issue
icon: symbol:number
regex: "^[A-Z]+-[0-9]+$"
url: https://example.com/browse/***

上記のサンプルでは選択テキストがABC-123のような形式に一致したときだけ表示されます。

他にも、特定のアプリでだけ表示したい場合はrequiredAppsにバンドルIDを指定します。

実行後の動作を決める

afterを指定すると、アクションの実行結果をどう扱うかを決められます。

対になるbeforeもあって、アクションの実行前にcopyやcutを挟めます。

シェルスクリプトの標準出力を選択範囲に戻す場合は、after: paste-resultを指定します。
URLを開くだけのアクションなど、テキストの結果を返さない処理には使えません。

Packagesにする

アイコン画像や別ファイルを同梱したい場合、または公式ディレクトリへ公開したい場合は、Packages（パッケージ形式）にします。

Packagesと言っても、.popclipextで終わる名前のフォルダを作ってその中に設定ファイルを置くだけです。

MyExtension.popclipext/
├── Config.yaml
├── icon.png
└── readme.md

今回の例では設定ファイルにConfig.yamlを使っていますが、他にJSONやplist、JavaScriptなどでも記述できます。

中身に書く内容はSnippetsと同じですが、公開する場合はname・identifier・description・popclip versionの4つが必須になります。

name: My Extension
identifier: com.example.myextension
popclip version: 6221
description: 選択したテキストを社内ツールで開きます。
icon: icon.png
url: https://example.com/search?q=***

identifierは拡張機能を識別する値なので、一意の名前を決めて、更新時も同じ値を使います。
popclip versionは必要なPopClipの最低バージョンのビルド番号で、上記サンプルでは2026.8.1（6221）以降を対象にしています。

icon.pngも実際の画像を用意します。
画像を使わない場合はicon: square filled ABのようなテキストアイコンに変更し、画像ファイルを省けます。

パッケージ化したら、フォルダをダブルクリックするとインストールされます。
なお、配布用にはフォルダをzipで圧縮して、拡張子を.popclipextzに変えたものを渡します。

自作した拡張機能を公開する方法

自分で使うだけなら前述のファイルだけで事足りますが、公式のディレクトリに載せることもできます。

www.popclip.app

PopClip Extensions Directory

https://www.popclip.app/extensions/

ディレクトリに掲載された拡張機能はサーバー側で署名されるので、インストール時に警告が出なくなりますし、更新も自動で配信されます。

提出の準備

公式の提出手順に沿って、公開したGitHubリポジトリを登録します。
2026年8月に新しい方式へ切り替わったようで、以前より手順が整理されました。

www.popclip.app

Submit an Extension — PopClip Extensions

https://www.popclip.app/extensions/submit

流れは下記の通りです。

1. 拡張機能を.popclipextパッケージとしてGitHubの公開リポジトリに置く
2. リポジトリのルートにpopclip-directory.yamlを作る
3. PopClip Directoryのアプリを対象のリポジトリにインストールする
4. バージョンのタグを付けてプッシュする

popclip-directory.yamlには、どのフォルダを拡張機能として扱うかを書きます。

include: "source/*.popclipext"
versionPrefix: v

この設定例では、パッケージをリポジトリ内のsource/フォルダに置きます。
ソースと設定ファイルをコミットしてGitHubへプッシュしたら、提出するコミットにバージョンのタグを付けて送ります。

git tag v1.0.0
git push origin v1.0.0

タグをプッシュすると自動チェックが始まり、結果をGitHubで確認できます。

サイズ制限は1つの拡張機能につきファイル数は100個まで、1ファイル1MiBまで、全体で2MiBまでです。

そしてreadme.mdを置くと、拡張機能のページに表示されます。
デモ動画（demo.mp4）を置くこともできて、こちらは目立つ位置に表示されます。

自動チェックを通ると手動レビューへ進みます。
それも承認されると、専用のページと署名済みの.popclipextzのダウンロードが用意されて公開されます。

シェルスクリプトは理由が必要

ひとつ注意したいのが、ディレクトリではJavaScriptで書くことが強く推奨されている点です。

シェルスクリプトを使う拡張機能を提出する場合は、shellScriptRationaleに「なぜJavaScriptでは実現できないのか」を書く必要があります。
理由は20文字以上が必要で、項目が無い場合は自動チェックを通りません。

公開を考えている場合は、JavaScriptで実現できる処理かを先に確認しておくと作り直しを減らせます。

まとめ

PopClipの拡張機能の自作は、想像していたよりずっと手前から始められました。
特に公開予定もなく、とりあえず自分で使う用のものであれば、YAMLを4行書いてそれを選択するだけで追加できます。

何よりテキストを選択するだけでインストール表示が出てくるのは、PopClipらしくて非常に面白いです。

まずは自分で試してみて、便利そうであれば公式ディレクトリへの申請も考えてみてはいかがでしょうか。