August 18th, 2019

Handling macOS URL schemes with Go

For a while I’ve had this idea of a custom browser handler in macOS that would have configurable rules for determining which browser a URL should open. I finally got around to building it which led to a lot of learning of what to-do and what not to-do when it comes to Cocoa apps and Go interop. If that sounds interesting you can find the code on GitHub, otherwise this post goes over how the core functionality of the application, macOS http/https URL scheme handling was written.

Initial Approaches

This project had a really bumpy start. The first task was to get a .app calling an executable. After getting this working, I soon realized that the url isn’t passed via STDIN, and it’s not available in os.Args. Turns out, macOS passes it via an event manager which Go doesn’t have access to.

The next approach was to define a simple AppleScript that would listen for a URL open event, then call the executable passing the URL. This seemed promising but sadly I couldn’t get it working.

With both of those options not panning out, there was clearly one choice left. Writing some Objective-C.

Objective-C and cgo

Thankfully Go has amazing support for C interop via cgo. Not only was using Objective-C possible, but it has strong support too. This meant that the Objective-C strategy was good to go (pun intended, sorry not sorry).

After a lot of trail and error, this is a minimal implementation that can actually listen for, and handle URL events.

To get started, first we need to define our Go code.

// main.go
package main

#cgo CFLAGS: -x objective-c
#cgo LDFLAGS: -framework Cocoa
#include "browse.h"
import "C"

import (

var urlListener chan string = make(chan string)

func main() {
	go C.RunApp()
	url := <-urlListener
	// replace with implementation
	cmd := exec.Command("open", "-a", "Safari", url)

//export HandleURL
func HandleURL(u *C.char) {
	urlListener <- C.GoString(u)

This is pretty straightforward, we’re defining the main package, then using cgo to tell the compiler to pass the CFLAGS -x objective-c telling it that we’re compiling Objective-C code. We’re also passing LDFLAGS which is telling the linker that we want to link the Cocoa framework. Finally, we import the header file that we’ll see in just a second. This is where our Objective-C code will go.

We also define a function that’s exported to C, HandleURL. The //export HandleURL directive above tells the compiler to make this function globally available in our C code. It’s also worth noting that the arguments it receives are from C so we end up receiving a C string which then has to be converted to a Go string via C.GoString.

The Objective-C pieces come in two parts, the header file and the source file.

// browse.h
#import <Cocoa/Cocoa.h>

extern void HandleURL(char*);

@interface BrowseAppDelegate: NSObject<NSApplicationDelegate>
    - (void)handleGetURLEvent:(NSAppleEventDescriptor *) event withReplyEvent:(NSAppleEventDescriptor *)replyEvent;

void RunApp();

The header file is pretty straightforward. We import Cocoa since this is technically going to be a Cocoa application. We define the exported Go function HandleURL as an external function that accepts a string and returns nothing so we’re able to call it from Objective-C.

Next we have to define an NSApplicationDelegate subclass. This is an object that defines lifecycle event methods that a Cocoa application will call. We have to implement some of the callbacks in order to hook up our event listener. We also define a method of our own, handleGetUrlEvent:withReplyEvent that we’ll define and use in just a second to receive URL events.

Finally, we define another function RunApp that will be called via Go to start the Cocoa application.

// browse.m
#include "browse.h"

@implementation BrowseAppDelegate
- (void)applicationWillFinishLaunching:(NSNotification *)aNotification
    NSAppleEventManager *appleEventManager = [NSAppleEventManager sharedAppleEventManager];
    [appleEventManager setEventHandler:self
                       forEventClass:kInternetEventClass andEventID:kAEGetURL];

- (void)handleGetURLEvent:(NSAppleEventDescriptor *)event
           withReplyEvent:(NSAppleEventDescriptor *)replyEvent {
    HandleURL((char*)[[[event paramDescriptorForKeyword:keyDirectObject] stringValue] UTF8String]);

void RunApp() {
    [NSAutoreleasePool new];
    [NSApplication sharedApplication];
    BrowseAppDelegate *app = [BrowseAppDelegate alloc];
    [NSApp setDelegate:app];
    [NSApp run];

There’s a lot of code here, but it’s largely boilerplate. We define the implementation for our BrowseAppDelegate and implement a NSApplicationDelegate callback, applicationWillFinishLaunching. We use this to get the shared event manager. Now that we have the event manager, we can add an event handler for URL open events that calls the handleGetURLEvent:withReplyEvent method we declared in our interface and define below.

In handleGetURLEvent:withReplyEvent we get the string value from the event, cast it from an NSString to a C string via UTF8String . We then need to cast that new C string to char* to prevent a compiler warning, but it’s not necessary for the code to compile or run.

Lastly, we have our RunApp function. This calls the necessary boilerplate methods for a Cocoa app, allocates memory for a new BrowseAppDelegate, sets it as the application’s delegate so our callbacks will be called, and tells the application to run.

We can make sure the code compiles by running go build.

Whew, that’s a lot of code just to get a single URL. Sadly, this still isn’t useful on its own. For the app to work we need to package the executable in a .app. Fortunately, this is mostly just more boilerplate.

Run the following in a terminal to create the .app along with the compiled application.

mkdir -p
go build -o

Last but not least, we need to create the plist. This defines metadata about the application including that we can handle http/https url’s.

To get the .app to register with macOS as a browser/URL handler, you can paste the following code into a new file,

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">
        <string>Web site URL</string>
        <string>FTP site URL</string>
        <string>Local file URL</string>

Now you should have a completely working macOS app! With that, we can drag and drop into the Applications folder. This should register as a browser and we can set it as the default browser in System Preferences -> General -> Default web browser.

Now each time you open a URL, your Go application handles the URL and should open Safari. It doesn’t add any new functionality, but this opens a whole world of possibilities for handling URL’s in macOS. It’s also worth noting that you can define your own URL schemes or handle URL schemes besides just http and https.