Junction

A rule-based link router for macOS. Junction sits as your default browser and routes every link you click to the right browser, browser profile, or native app, based on rules you define.

Open source (MIT) · GUI and a version-controllable JSON config file · CLI included · zero telemetry.

Website and docs: junction.jnahian.me

Why

macOS allows exactly one default browser. If you juggle work and personal Chrome profiles, want Zoom links in the Zoom app instead of a tab, or want Terminal links in a different browser than Mail links, you need a router in between. Choosy is paid, Velja is closed source, Finicky has no GUI. Junction is the open-source option with a first-class GUI and a human-readable config file you can check into your dotfiles.

How it works

1. Junction registers as your default browser (it's a menu bar app: no windows, no Dock icon).
2. Every clicked http(s) link goes through your ordered rule list; first match wins.
3. Rules match on URL wildcards (*.atlassian.net/*), regex, and/or the source app the click came from.
4. Actions: open in a browser, open in a specific browser profile (Chromium or Firefox), rewrite to a native app deep link (17 built in, including Zoom, Spotify, Slack, Figma, Notion, Teams, Discord, Linear, Telegram, WhatsApp, Apple Music), show a picker, or copy to clipboard.
5. Anything unmatched goes to your fallback — a browser, or the picker if you'd rather be asked every time. A link is never lost.

Hold ⌥ Option while clicking any link to force the picker. Links sent to the picker while it is open collect in one list; choosing a browser opens all of them, and Copy Links copies them on separate lines. Esc or clicking away cancels the whole list.

Config file

Rules live in ~/.config/junction/config.json (respects $XDG_CONFIG_HOME). Edit them in the GUI or in your editor. The file is watched and hot-reloads with validation: invalid edits keep the last-good rules and show a menu bar warning. Comments and trailing commas are accepted on read; the GUI writes strict, stably-sorted JSON so git diffs stay clean.

{
  "version": 1,
  "fallback": { "app": "com.apple.Safari" },
  "stripTrackingParams": true,
  "rules": [
    {
      "name": "Work links → Chrome work profile",
      "match": { "patterns": ["*.atlassian.net/*", "app.clickup.com/*"] },
      "action": { "app": "com.google.Chrome", "profile": "Profile 1" }
    },
    {
      "name": "Zoom → native app",
      "match": { "patterns": ["*.zoom.us/j/*", "*.zoom.us/w/*"] },
      "action": { "deepLink": "zoom" }
    },
    {
      "name": "Personal → Firefox profile",
      "match": { "patterns": ["reddit.com/*", "news.ycombinator.com/*"] },
      "action": { "app": "org.mozilla.firefox", "profile": "personal" }
    },
    {
      "name": "Links from Terminal → Chrome",
      "match": { "sourceApps": ["com.googlecode.iterm2", "com.apple.Terminal"] },
      "action": { "app": "com.google.Chrome" }
    }
  ]
}

profile is a profile's name, as listed in Settings → Browsers (for Firefox, the one firefox -P takes). Chromium browsers also accept the profile directory (Default, Profile 1), but a directory can mean a different profile on another Mac, so the rule editor saves the name. Listing profiles needs Full Disk Access; without it, a Chromium profile still works if you type its directory into the config file, but a rule that uses a profile name, like any Firefox profile rule, falls back to your fallback browser. If a rule names a profile that doesn't exist on this Mac, the link degrades to your fallback browser rather than opening in the wrong one.

To sync across Macs, turn on Sync rules across your Macs under Settings → General on each one. Junction keeps a copy of config.json in the Junction folder in iCloud Drive. Each Mac still routes from its own file, so links keep working offline and the CLI is unchanged. If two Macs change the rules at once, the newest change wins and the other is saved as config.backup.json.

app can also be a Chrome web app (one installed with Install page as app), named by its bundle ID. The rule editor lists them under Web apps, or osascript -e 'id of app "ClickUp"' prints the ID, e.g. com.google.Chrome.app.edcmabgkbicempmpgmniellhbjopafjh. The link opens in the web app's own window. Junction looks up which profile the web app is installed in, which needs Full Disk Access like the profile list; without it, set profile on the rule in the config file. A link from a different site than the web app's goes to your fallback browser, because the web app would drop it and show its home page.

fallback.app is a browser bundle ID, or the special value "picker" to be asked with the picker on every unmatched link.

picker sets how the picker looks, and every field is optional: "layout" is "vertical" (the default list) or "horizontal" (a row that wraps), "labels" is "name" or "none" for icons only, and "iconSize" is 16–64 points (default 22). For example, "picker": { "layout": "horizontal", "labels": "none", "iconSize": 40 }. Settings → Browsers → Picker appearance edits the same values.

Pattern semantics: matched against host/path, scheme ignored unless written. * stays within a segment, ** (or a trailing *) crosses segments, *.example.com includes the apex domain, bare example.com matches all subpaths. Host is case-insensitive, path case-sensitive, query ignored (use regex when the query matters).

CLI

The app bundle ships a companion CLI (Homebrew links it automatically):

junction test "https://mycorp.atlassian.net/browse/X-1" --source com.tinyspeck.slackmacgap
junction open "https://example.com"
junction config path
junction config validate

Install

Requirements: macOS 13 Ventura or later. Builds are universal — Apple silicon and Intel.

This is the beginning of the README. Read the rest at the original. Read the full README ↗