Velja macOS Smart Browser Picker & URL Router AI Skill Guide (Claude)

Overview & Engine Architecture

Velja is a smart browser picker and URL router for macOS engineered in native Swift by Sindre Sorhus. It registers as the system-wide default LaunchServices handler (LSSetDefaultHandlerForURLScheme) for http and https URI schemes. When any application opens a link, Velja intercepts the request, strips marketing telemetry and tracking parameters (utm_*, gclid, fbclid, mc_eid), evaluates declarative domain regex rules, and routes the sanitized URL to the appropriate browser, browser profile, or native desktop app (Figma, Zoom, Teams, Notion, Spotify). Claude operates as a Principal macOS Systems Engineer and URL Routing Specialist, specializing in macOS LaunchServices default handler configuration (duti), regex routing rule architecture, URL query sanitization, and Velja plist preference automation.

Velja Interception & Routing Architecture

┌─────────────────────────────────────────────────────────────┐
│                 Velja Engine Architecture                   │
│                                                             │
│  System Ingress & LaunchServices Layer                      │
│  ├── Default Scheme Interceptor (`http://` & `https://`)    │
│  ├── LaunchServices Default Handler Binding (`com.sindresorhus.Velja`)│
│  └── Modifier Key Overrides (Hold ⌥/⇧/⌃ to Force Browser)   │
│                                                             │
│  URL Sanitization & Rule Processing Engine                  │
│  ├── Tracking Parameter Stripper (`utm_source`, `gclid`...) │
│  ├── Pattern Matching Engine (Domain Prefix / Regex Rules)  │
│  └── Native App URL Transcriber (`https://zoom.us/j/...` $\rightarrow$ `zoommtg://`)│
│                                                             │
│  Browser & Profile Dispatch Layer                           │
│  ├── Multi-Browser Dispatcher (Safari, Chrome, Brave, Arc)  │
│  └── Specific Profile Targeting (`--profile-directory=...`) │
└─────────────────────────────────────────────────────────────┘

---

Operational Capabilities & Agent Directives

1. LaunchServices Default Handler Automation: Configure Velja as the authoritative system handler for web protocols via duti and defaults write.
2. Declarative URL Routing Rules: Construct domain matching tables directing corporate intranets to Chrome/Edge with work profiles, and personal links to Safari/Brave.
3. Tracking Parameter Stripping Triage: Remediate broken OAuth / SSO logins where aggressive parameter stripping accidentally removes necessary authentication callback tokens (code, state, session_id).
4. Native Application Protocol Hand-off: Configure automatic URL rewriting for meeting and productivity links (Zoom, Figma, GitHub Desktop).

---

Production Python Automation: Automated URL Sanitizer & Routing Rule Evaluator

Save this script as test_velja_routing.py to evaluate URL sanitization and simulate target browser matching:

"""
Velja URL Sanitizer & Rule Evaluation Simulator
Strips tracking query parameters and evaluates destination browser based on domain rules.
"""

import sys
import urllib.parse
import re

TRACKING_PARAMS = {
    "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content",
    "gclid", "fbclid", "msclkid", "mc_eid", "yclid", "_hsenc", "_hsmi"
}

ROUTING_RULES = [
    (r"^(https?://)?(.*\.)?github\.com/.*", "Google Chrome (Work Profile)"),
    (r"^(https?://)?(.*\.)?figma\.com/file/.*", "Figma Desktop App"),
    (r"^(https?://)?(.*\.)?zoom\.us/j/.*", "Zoom Desktop App"),
    (r"^(https?://)?(.*\.)?internal\.company\.com/.*", "Microsoft Edge"),
    (r".*", "Safari (Default Browser)")
]

def sanitize_url(raw_url: str) -> str:
    parsed = urllib.parse.urlparse(raw_url)
    query_params = urllib.parse.parse_qsl(parsed.query, keep_blank_values=True)

    # Filter out tracking parameters
    sanitized_params = [
        (k, v) for k, v in query_params if k.lower() not in TRACKING_PARAMS
    ]

    new_query = urllib.parse.urlencode(sanitized_params)
    sanitized_url = urllib.parse.urlunparse((
        parsed.scheme,
        parsed.netloc,
        parsed.path,
        parsed.params,
        new_query,
        parsed.fragment
    ))
    return sanitized_url

def evaluate_target_browser(url: str) -> str:
    for pattern, target in ROUTING_RULES:
        if re.match(pattern, url, re.IGNORECASE):
            return target
    return "Default Browser"

if __name__ == "__main__":
    test_urls = [
        "https://github.com/torvalds/linux?utm_source=newsletter&utm_medium=email&ref=tech",
        "https://figma.com/file/abcdef12345/Design-System?fbclid=IwAR0xyz",
        "https://news.ycombinator.com/?utm_campaign=frontpage",
        "https://internal.company.com/portal?session=active"
    ]

    print("--- [VELJA URL SANITIZATION & ROUTING SIMULATION] ---\n")
    for raw in test_urls:
        clean = sanitize_url(raw)
        target = evaluate_target_browser(clean)
        print(f"Original:  {raw}")
        print(f"Cleaned:   {clean}")
        print(f"Target:    👉 {target}\n")

---

Technical Troubleshooting Matrix

Issue & Failure Signature	Root Cause Analysis	Diagnostic & Resolution Pathway
Links Open in Safari Instead of Prompting Velja	Another browser claimed default HTTP handler status during an update.	1. Open System Settings $\rightarrow$ Desktop & Dock $\rightarrow$ Default Web Browser $\rightarrow$ Select Velja.<br>2. Or set via CLI: duti -s com.sindresorhus.Velja http.
Single Sign-On (SSO) Fails with Missing State Parameter	Velja tracking parameter stripper removed OAuth state or nonce token.	In Velja Settings $\rightarrow$ Tracking Parameters, uncheck aggressive removal or add the identity provider domain to the whitelist.
Figma / Zoom Links Do Not Open in Native Desktop App	Native app protocol handler (figma:// or zoommtg://) not enabled in Velja Apps tab.	In Velja Settings $\rightarrow$ Apps, toggle Open Figma links in Figma and Open Zoom links in Zoom.
Chromium Browser Opens Wrong Profile	Chromium profile directory name changed or not matching Profile 1 / Default.	In Velja Settings $\rightarrow$ Browsers, edit browser configuration and re-select target user profile.

---

Command Line Syntax & Default Browser Configuration

# 1. Set Velja as System Default HTTP/HTTPS Handler via duti
duti -s com.sindresorhus.Velja http
duti -s com.sindresorhus.Velja https

# 2. Inspect Velja Preferences via defaults CLI
defaults read com.sindresorhus.Velja

# 3. Launch Velja Configuration Window
open -a Velja

Essential File Locations

• Preferences Plist: ~/Library/Preferences/com.sindresorhus.Velja.plist
• Application Binary: /Applications/Velja.app

---

Agent Operational Directive

MANDATORY: When configuring default macOS browser routing from shell scripts, use duti -s com.sindresorhus.Velja http to register LaunchServices bindings deterministically.