📑 Table of Contents (Click to expand)

1. About The Project
2. Built With
3. Key Features
4. Visual Showcase
5. How It Works (Architecture)
   • Windows Job Object Detachment
   • Tailored Profile Directory Targeting
   • Registry & Local State Discovery
   • Zero-Overhead Input Classification
6. Supported Browsers
7. Keyboard Shortcuts
8. Getting Started
9. Privacy & Security
10. License

---

About The Project

On macOS, Raycast power users easily route links to specific browser profiles. On Windows, however, users face frustrating roadblocks:

• System Default Lock-in: Windows delegates all links strictly to your default browser, forcing you to manually copy-paste URLs across profiles.
• Multi-Profile Chaos: Developers, founders, and students juggle distinct profiles (Personal, Work, Client Staging, College). Switching between them requires opening the browser first, clicking the avatar menu, and navigating to the target account.
• The Windows Sandbox / Isolation Bug: Naive attempts to launch Chromium browsers with --profile-directory from within packaged Windows apps or node child processes run into Windows Job Object / AppContainer isolation. This opens browsers in phantom/guest sessions where cookies, active logins, and sessions are lost.

Browser Router solves all three problems with a sub-35ms native detachment engine, deep registry-driven profile detection, and an intelligent URL/query classification lexer.

---

Built With

Browser Router is built with modern, lightweight, and type-safe technologies:

• — Native Windows desktop UI and action system
• — Type safety and robust data structures
• — Declarative component architecture
• — Libuv detached process spawning
• — Encrypted serverless edge relay for feedback

---

Key Features

• ⚡ Instant Native Dispatch (< 35ms)
  Launches browser profiles directly into the interactive Windows desktop session with zero perceptible delay.

• 🎯 Dual-Mode Input Routing
  Seamlessly accepts queries from Raycast Root Search (press Tab) or acts as an automatic Fallback Command.

• 🔍 Deep Profile & Avatar Auto-Discovery
  Scans the Windows Registry and parses browser metadata (Local State plus profile avatars) to discover profiles, display names, and profile pictures.

• 🌐 Smart URL vs. Query Classification
  Differentiates between plain text searches, bare domains (github.com), and local dev servers (localhost:3000, 127.0.0.1:8080).

• 🏷️ Custom Profile Names & Portable Setups
  Assign custom nicknames ("Stripe Staging", "Personal") or connect custom browser executables and portable folders.

• 🎨 Configurable Search Engines
  Switch between Google, DuckDuckGo, Brave Search, Bing, Perplexity, Ecosia, or specify a custom URL template with %s.

• 🔒 100% Offline & Private
  No tracking, no analytics, no background services. Only voluntary in-app feedback uses an encrypted HTTPS edge relay.

---

Visual Showcase

1. Root Search Fast Routing Type your search query directly from Raycast Root Search with Tab-completion.	2. Intelligent Query & URL Lexing Auto-detects localhost, dev ports, bare domains, and search queries.
3. Real-Time Profile Filtering Filter profiles instantly by browser brand, account email, or nickname.	4. Power Action Panel Instant access to profile renaming, custom setups, link copying, and feedback.
5. In-Place Profile Renaming Assign clean labels without modifying browser preferences on disk.	6. Custom & Portable Setups Add portable installations, custom directories, or Canary builds.

---

How It Works (Architecture)

Browser Router is engineered specifically to overcome the constraints of Windows packaged desktop applications.

flowchart TD
    subgraph Input ["1. User Input in Raycast"]
        A[User Query or URL] --> B[Browser Router Command]
    end

    subgraph Lexer ["2. Intelligent Lexer"]
        B --> C{Input Type?}
        C -->|Bare Domain / Localhost / URL| D[Format Web Protocol]
        C -->|Search Query| E[Interpolate Engine Template]
    end

    subgraph Discovery ["3. Registry & Profile Resolver"]
        D --> F[Locate Target Browser & User Data Dir]
        E --> F
        F --> G[Extract Profile Directory & Local State]
    end

    subgraph Launcher ["4. Native Detachment Engine"]
        G --> H["spawn(exe, args, { detached: true })"]
        H --> I["child.unref()"]
        I --> J[Browser Opens in Active User Session]
    end

1. Escaping the Windows Job Object Sandbox

When an extension executes inside Raycast on Windows, child processes spawned via conventional APIs (child_process.exec, open, or shell.openExternal) inherit Raycast's parent process group and Windows Job Object boundaries.

Because modern Chromium browsers enforce single-instance IPC checks and DPAPI master key encryption based on interactive user desktop security tokens, running inside an inherited job container causes Chromium to fail to acquire write locks on profile SQLite databases (Cookies, Web Data, Login Data), opening a blank, unauthenticated session.

The Solution: Browser Router uses low-level Libuv process detachment:

const child = spawn(browserExePath, launchArgs, {
  detached: true,
  stdio: "ignore",
  windowsHide: false,
});
child.unref();

detached: true instructs Windows' CreateProcessW API to detach from the parent job tree. child.unref() immediately removes the child from Node's event loop. The Windows kernel attaches the browser process directly to the user's interactive Desktop session (Session ID 1), ensuring 100% authentic login persistence.

2. Tailored Profile Directory Targeting Architecture

Launching browser profiles reliably on Windows requires a tailored command-line strategy:

• Brave, Vivaldi, Arc, Opera & Custom Profiles: Browser Router dynamically detects and pairs the root user data directory with the profile folder:

  const launchArgs = [
    `--user-data-dir=${browser.userDataDir}`,
    `--profile-directory=${profile.directoryName}`,
    targetUrl,
  ];
  

  This guarantees deterministic profile targeting and prevents MSIX container virtualization.

• Google Chrome & Microsoft Edge: Passes --profile-directory=${profile.directoryName} while deliberately omitting --user-data-dir. This respects Chrome's singleton process model (preventing profile detachment and session logout) and avoids conflicts with Edge's background Startup Boost locks.

3. Registry & Local State Metadata Discovery

Rather than hardcoding filesystem paths, Browser Router inspects both Windows Registry hives:

• HKCU\Software\Clients\StartMenuInternet (Per-user installations)
• HKLM\Software\Clients\StartMenuInternet (System-wide installations)

It reads the registered shell command, extracts the executable binary, and parses:

• Local State: Extracts profile display names, high-resolution badge icons, and Google/Microsoft account emails.
• Profile Avatars: Resolves cached profile pictures and custom avatar assets from the profile directory.

4. Zero-Overhead URL & Query Classification

An instantaneous regex-free tokenizer classifies user input in real time:

• Full URLs: Matches valid schemas (https://, http://, file://, and browser-internal protocols like chrome://, edge://, brave://).
• Localhost & Ports: Matches localhost, 127.0.0.1, ::1, and custom port bindings (:3000, :8080).
• Bare Domains: Identifies valid top-level domains (.com, .dev, .ai, .org, etc.) and automatically prepends https://.
• Search Queries: Cleanly URL-encodes multi-word queries into your chosen engine template.

---

Supported Browsers

Browser	Auto-Discovery	Multi-Profile	Custom Avatars	Windows Support
Google Chrome	✅	✅	✅	Win 10 / 11
Microsoft Edge	✅	✅	✅	Win 10 / 11
Brave Browser	✅	✅	✅	Win 10 / 11
Vivaldi	✅	✅	✅	Win 10 / 11
Arc for Windows	✅	✅	✅	Win 11
Mozilla Firefox	✅	✅	❌	Win 10 / 11
Opera & Opera GX	✅	⚠️	❌	Win 10 / 11
Custom / Portable	✅	✅	✅	Win 10 / 11

---

Keyboard Shortcuts

Shortcut	Action	Scope
↵ Enter	Launch in Selected Browser & Profile	Profile List
Ctrl + ↵ Enter	Open in Incognito / InPrivate	Profile List
Tab	Toggle Filter / Search Query Mode	Profile List
Ctrl + F	Pin / Unpin Favorite Profile	Profile Item
Ctrl + E	Rename Profile (Local Nickname)	Profile Item
Ctrl + N	Add Custom Profile / Portable Browser	Profile List
Ctrl + Backspace	Delete Custom Profile	Custom Item
Ctrl + H	Open User Manual & Guide	Global
Ctrl + Shift + F	Send Feedback / Report Bug	Global
Ctrl + Shift + X	Clear Active Search Query	Profile List
Ctrl + C	Copy Target Destination URL	Profile Item
Ctrl + R	Refresh Browsers & Profiles	Global
Ctrl + ,	Open Extension Preferences	Global

---

Getting Started

Installation via Raycast Store

Search for Browser Router in the Raycast Store and click Install Extension.

Local Development Setup

1. Clone the repository:

   git clone https://github.com/raycast/extensions.git
   cd extensions/browser-router
   

2. Install dependencies:

   npm install
   

3. Start developer mode:

   npm run dev
   

4. Verify quality & linting:

   npm run lint        # Validates package.json, icons, metadata, ESLint, Prettier
   npm run fix-lint    # Auto-fixes any formatting inconsistencies
   npm run build       # Creates production bundle
   

---

Privacy & Security

• Zero Telemetry: Browser Router collects no telemetry, metrics, or analytics.
• No Access to Sensitive Data: Never accesses browsing history, saved passwords, cookies, or DPAPI master keys.
• 100% On-Device Operation: All detection and routing occur strictly on your local PC.
• Read our full Privacy Policy and Security Policy.

---

License

Distributed under the MIT License. See LICENSE for more information.

Copyright (c) 2026 Raghav Gupta. All rights reserved.