org-protocol-handler

KO | EN

gitlite — search

#typescript #ai-agents #deepseek-harness #dsh-plugin #open-source #ai #cli #dsh #claude-code #codex #developer-tools #react

org-protocol-handler

★ 56 Open GitHub ↗

An OS X application that handles org-protocol:// links.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Org Protocol Handler #

The Org Protocol Handler is a small AppleScript/Python application that
registers itself as the handler for all `org-protocol://` links.

If your system wants to visit an `org-protocol://` link, it will pass the value
to this application, which will urldecode it and pass it to `emacsclient`. The
net effect is that you can use a bookmarklet to build an `org-protocol://` link
in your browser for things like saving the current page as a link in Org and
that bookmarket will launch and focus Emacs.

## Configuration ##

In order for this application to work for you, you will need to be sure that it
is pointed to the correct copy of `emacsclient` on your system.

Out of the box, it will run `/usr/local/bin/emacsclient`, which should be the
correct copy if you are using Emacs from Homebrew. If you are not, or if that
path differs in some way, you will need to create a configuration file.

Create a file called `~/.orgprotocol.ini`. Note the leading period in the
filename. This file should simply contain these two lines:

```
[emacsclient]
path=/path/to/your/emacsclient
```

## How does it work? ##

In OS X, any application that exists in your root `/Applications` directory and
that contains a `CFBundleURLTypes` stanza in its `Info.plist` will be registered
as a handler for the URL schemes described there.

In the case of this application, the stanza looks like this:

```
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>EmacsClientCapture</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>org-protocol</string>
        </array>
    </dict>
</array>
```

In my understanding, the `CFBundleURLName` makes no difference at all, it just
needs to be set to something. When any program on your system attempts to visit
a URL beginning with `org-protocol://`, OS X will launch this application and
hand it the URL through some known OS X API mechanism.

In AppleScript, accessing that data is quite simple, you need only define an `on
open location` subroutine that accepts the whole URL as a string and then you
can do what you like with it.

This application is designed to accept an `org-protocol://` URL and it simply
launches `emacsclient` and hands that URL to it. This enables your
already-running Emacs server to be triggered by `org-protocol://` links from
anywhere on your system.

Neither the `emacsclient` program nor Emacs itself will decode the URL; it
expects to receive a raw URL with spaces and all, but the URL will need to be
encoded to preserve spaces (especially) when the handler is called by your
browser, so this handler uses a small Python script to decode the URL and also
extract the page title from it so we can display a notification.

## Why? ##

In short, so that you can save things from your web browser directly into Org
capture templates or simply save the links to pages for later insertion into Org
documents.

org-protocol-handler

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README