Velja

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

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.