Get started

Install Grinch

Grinch needs macOS 13 or later. Releases are universal binaries for Apple silicon and Intel Macs, signed with a Developer ID and notarized by Apple.

Download the latest Grinch-vX.Y.Z.dmg from the releases page, open it, and drag Grinch.app onto the Applications shortcut in the DMG window.

Install to /Applications directly. Running Grinch.app from ~/Downloads or anywhere else triggers Gatekeeper translocation, which makes the same app appear several times in the default-browser picker.

From the terminal

This script finds the latest DMG through the GitHub API, downloads it, copies Grinch.app into /Applications, and opens it:

DMG=$(curl -fsSL https://api.github.com/repos/jamtur01/grinch/releases/latest \
  | grep -oE '"browser_download_url": "[^"]*\.dmg"' | cut -d'"' -f4)
curl -fsSL "$DMG" -o /tmp/grinch.dmg
hdiutil attach -nobrowse -quiet /tmp/grinch.dmg
ditto "/Volumes/Grinch "*/Grinch.app /Applications/Grinch.app
hdiutil detach "/Volumes/Grinch "* -quiet
open /Applications/Grinch.app

With Homebrew

A community-maintained cask is available from bric3/tap. It is maintained outside the Grinch project.

brew tap bric3/tap
brew install --cask grinch

From source

Building needs Rust stable through rustup; the contributor prerequisites list the tools. Ad-hoc signed builds don't include automatic updates.

git clone https://github.com/jamtur01/grinch
cd grinch
make run

Write your first rule

Grinch reads its rules from a JavaScript file. Create ~/.config/grinch.js with this content:

module.exports = {
  default: "com.apple.Safari",
  rules: [
    { match: "github.com", open: "com.google.Chrome" },
  ],
};

This sends github.com and its subdomains to Chrome, and every other link to Safari. Use apps you have installed: a target can be any app that can open the URL, such as Zoom or Slack. If ~/.config doesn't exist, create it first with mkdir -p ~/.config.

Only use configs you trust. Grinch runs the config file as JavaScript.

The commands on this site call the binary inside the app. Add this alias to your shell, or use the full path each time:

alias Grinch='/Applications/Grinch.app/Contents/MacOS/Grinch'

To find the bundle ID of a browser or app, list every app registered to open web links:

Grinch --list-browsers
com.apple.Safari               Safari
com.google.Chrome              Google Chrome
com.brave.Browser              Brave Browser
com.microsoft.edgemac          Microsoft Edge
app.zen-browser.zen            Zen
...

App names such as "Google Chrome" work too. The configuration reference covers profiles, other match types, and rewrites.

Launch Grinch

Open Grinch from Applications. Its eyes appear in the menu bar. Click them for Open Config, Reload Config, Open Diagnostic Log, and update checks. The menu bar reference lists every item.

macOS also asks whether Grinch may use Accessibility. Grinch only needs it for rules that read the title of the window a link came from. You can decline now and allow it later under System Settings → Privacy & Security → Accessibility.

Make Grinch your default browser

Open System Settings → Desktop & Dock → Default web browser and choose Grinch. Links you open in other apps now go through your rules.

Check a link

Ask Grinch where a link would go, without opening a browser:

Grinch --test "https://github.com/jamtur01/grinch"
URL:     https://github.com/jamtur01/grinch
Final:   https://github.com/jamtur01/grinch
Browser: com.google.Chrome
Grinch --test "https://example.com/"
URL:     https://example.com/
Final:   https://example.com/
Browser: com.apple.Safari

Then click a GitHub link in Slack or Mail. It opens in Chrome. If it doesn't, Troubleshooting shows how to find out why.