Managing Engines

Quiper does not restrict you to a single AI ecosystem. You can manage and organize cloud engines (like ChatGPT, Claude, and Gemini) alongside local engines (like Ollama or Open WebUI) in a single unified list.

---

Engine Configuration Settings

To add or configure an engine:

1. Open Settings (⌘ ⇧ ,) and navigate to the Engines tab.
2. Select an existing engine to edit, or click Add Engine in the toolbar, then choose Blank or select bundled templates and confirm.
3. Each engine exposes the following properties:
   • Name: The label displayed in the switcher tab (e.g., "ChatGPT").
   • Engine Type: Single URL or Pinned Tabs (see below).
   • URL: For Single URL engines, the target web address every new tab opens (e.g., https://chatgpt.com). For Pinned Tabs engines, replaced by a fixed per-tab URL list.
   • Prompt Input: The CSS selector identifying the editable prompt field.
   • Custom CSS: Overrides to style the web elements (see the Custom CSS Injection section below).
   • Domain Routing Rules: An ordered list of regex patterns that decide how outbound links from this engine are handled (see below).
   • Activation Shortcut: A dedicated hotkey that summons the window and immediately opens this engine.

---

Pinned-Tab Engines

A Single URL engine opens the same address in every tab. A Pinned Tabs engine pins a fixed URL to each of its ten tab slots instead: every tab always opens its pinned address.

To switch types, open Settings (⌘ ⇧ ,) ➔ Engines ➔ [Select Engine] ➔ URL and use the Engine Type picker:

• Single URL → Pinned Tabs: The current engine URL seeds the first tab slot; the remaining slots start empty. Live tabs reload.
• Pinned Tabs → Single URL: The first non-empty pinned URL becomes the engine URL and the other pinned URLs are removed. This can't be undone. Live tabs reload.

Tab URLs

• Edit the ten slots under Settings ➔ Engines ➔ [Select Engine] ➔ URL. Empty slots have no session; only slots with a URL open.
• Reorder URLs with the up/down chevrons to move them between tabs.
• Closing a tab never loses it: selecting that tab again reopens its pinned address. Saved sessions and backups never carry pinned addresses separately — the definition is the source of truth, including after relaunch.
• The engine icon is fetched from the first non-empty pinned URL.

Link Behavior

A pinned tab changes its address only when you ask it to:

• Reloading the pinned address itself (ignoring #fragment and a trailing /) stays in the tab — along with any redirect the server answers it with, which is the reload's own continuation.
• Open Link Here — the context-menu item, an ⌥-click, or the routing prompt's Open Here choice — shows the link in the tab right away, as the explicit instruction it is; the pinned address steps aside for it, and the drift is transient.
• Everything else leaves the tab: link clicks open in a popup or the system browser, and form submits/script navigations open in a popup sharing the engine's storage (so auth bounces keep their sessions).
• Routing rules offer only Popup and Safari for new rules. Existing Internal rules open in a popup instead, and Prompt rules still prompt — with Open Here as a one-off explicit instruction alongside the popup and browser choices. Remembered Open Here choices are stored as popups: a pinned tab never stays by rule.

---

Engine Icons

Every engine in your selector bar displays an icon. Quiper provides three ways to manage these icons under Settings ➔ Engines ➔ [Select Engine]:

1. Automatic Fetching

• When you enter or change an engine's URL in settings, Quiper automatically attempts to fetch the website's favicon in the background using a built-in resolver.
• You can manually trigger this by clicking the engine icon box, opening the drop-down menu, and selecting Fetch Automatically.

2. Custom Files

• If you want to use a high-resolution icon or a customized graphic, click the icon box and select Choose File....
• Quiper supports standard image formats (.png, .jpg, .jpeg). Once selected, the image is automatically resized, encoded as a Base64 string, and saved directly into your settings file, ensuring it is portable.

3. Manual Reset/Removal

• To remove a custom icon, open the icon box menu and select Remove Icon.
• This removes the icon from the settings structure and reverts the engine to the default Globe icon (globe SF Symbol).

---

Prompt Input Selectors Explained

One of the key usability features in Quiper is auto-focus. When you summon the overlay or switch to an engine, Quiper automatically places your keyboard focus inside the text input box so you can start typing immediately without using your mouse.

To do this, Quiper evaluates a short script:

document.querySelector("[your-focus-selector]")?.focus();

Finding the Correct Prompt Input Selector

If you add a custom engine and notice that your keyboard focus doesn't land in the input box, you need to find the element's CSS selector:

1. Summon the engine inside Quiper.
2. Press ⌘ ⌥ I to open the Web Inspector.
3. Click the Inspect Element pointer icon at the top-left of the inspector.
4. Hover over the input area on the page and click it.
5. In the inspector's HTML structure pane, right-click the highlighted input element (usually a textarea or a div with contenteditable="true").
6. Select Copy ➔ SelectorPath (or Copy ➔ CSS Selector).
7. Paste this string into the Prompt Input field in settings.

For built-in engine templates, enable Use Latest Default to follow selector updates bundled with future Quiper versions. Disable it whenever you want to keep an editable custom selector.

Default Selectors for Common Engines

Engine	Prompt Input Selector
Gemini	rich-textarea .textarea, .textarea, div[contenteditable='true'], textarea
Claude	[data-testid='chat-input'] div[contenteditable='true'], div[contenteditable='true'], textarea
Grok	textarea[aria-label='Ask Grok anything'], textarea, div[contenteditable='true']
ChatGPT	#prompt-textarea, textarea, div[contenteditable='true']
X (Grok)	div[contenteditable='true'], textarea
Open WebUI	#chat-input[contenteditable='true'], textarea, div[contenteditable='true']
Z.ai	textarea, div[contenteditable='true'], [role='textbox']
DeepSeek	textarea, div[contenteditable='true'], [role='textbox']

---

Custom CSS Injection

Since Quiper runs AI interfaces inside WKWebView wrappers, you can inject custom CSS styles directly into any engine's document head. This is most commonly used to hide sidebars, change scrollbars, and make backgrounds transparent so that your native macOS blur effects shine through.

Setting Up Custom CSS

1. Open Settings (⌘ ⇧ ,) ➔ Engines.
2. Select the engine you want to style.
3. Scroll down to the Custom CSS text box.
4. Paste your CSS rules and click Save.
5. Press ⌘ R to reload the active web view and see your styles applied live.

For built-in engine templates, enable Use Latest Default to follow stylesheet updates bundled with future Quiper versions. Disable it to materialize the current default as editable custom CSS.

Custom CSS Templates

Below are ready-to-use CSS configurations to make the backgrounds transparent for the default engines:

Gemini

body, 
mat-sidenav-container, 
response-container>* {
  background-color: transparent !important;
}

input-container::before {
  background: transparent !important;
}

Claude

body, 
.bg-bg-500, 
.bg-bg-400, 
.bg-bg-300 {
  background-color: transparent !important;
}

Grok

body {
  background-color: transparent !important;
}

.chat-input-backdrop {
  background-image: none;
}

ChatGPT

html, 
body {
  background-color: transparent !important;
}

X (Grok)

body, 
div[data-testid="primaryColumn"] {
  background-color: transparent !important;
}

Finding Classes for Overrides

If you want to write your own overrides (e.g. hiding a specific left-hand menu sidebar):

1. Summon the active engine in Quiper.
2. Press ⌘ ⌥ I to open the Web Inspector.
3. Click the inspection cursor and highlight the sidebar you wish to hide.
4. Identify its CSS class or element type (e.g., <div class="sidebar-container-xyz">).
5. Add the rule to your Custom CSS text area:

   .sidebar-container-xyz {
     display: none !important;
   }

6. Reload the view (⌘ R).

---

Integrating Local Engines

You can easily point Quiper to local web applications running LLM interfaces:

Open WebUI (Local Docker Instance)

1. Ensure your Docker container is running (http://localhost:8080).
2. Create a new engine in settings.
3. Set the URL to: http://localhost:8080.
4. Set the Prompt Input selector to: #chat-input[contenteditable='true'] (or #chat-input).

Ollama / Llama.cpp Web Servers

• If you run custom GUI interfaces for Ollama or Llama.cpp (like llama.cpp/examples/server), simply set the URL to your local port (e.g. http://127.0.0.1:8080) and input the target text input's CSS class or ID.

---

Domain Routing Rules

Every engine has its own Domain Routing editor (Settings ➔ Engines ➔ [Select Engine] ➔ Domain Routing) that decides what happens when a link inside that engine points somewhere other than the engine's own site — for example, an OAuth login redirect, a citation link, or an external documentation page.

How a Link Is Routed

1. Same-Origin Priority: Links to the engine's own domain (or its subdomains) always open inline, regardless of any rule — this guarantees normal in-app navigation is never intercepted. Exception: Pinned Tabs engines have no same-origin fast path — only the pinned address itself stays; everything else leaves the tab (see Pinned-Tab Engines).
2. Ordered Rule Matching: For every other link, Quiper walks the Routing Rules list from top to bottom and applies the action of the first rule whose regex pattern matches the URL. Reorder rules with the chevrons next to each row to control priority.
3. Default Fallback: If no rule matches, the link opens externally in your default system browser.
4. Modifier Overrides: The modifiers you hold at the moment of the click pick the destination directly, overriding whatever the rules decided: ⌘ opens the link in a new Quiper window, ⌥ opens it right in the current tab — the same Open Link Here action as the context menu, in every engine — ⌘⌥ sends it to the system browser, ⌘⇧ opens it in a private window. The link's context menu shows these as right-aligned shortcuts on its items, and its bold follows the modifiers you hold, so the highlighted item is the one your click will perform. One outcome still stands over every modifier: a link with a download attribute downloads.

These rules decide where a navigation starts. Once a navigation is allowed to continue in Quiper — in the tab or in a popup — its redirects continue with it, so a redirected page lands where its navigation was going instead of the redirect being routed again.

Routing Actions

Action	Behavior
Internal	Loads the URL inside the current Quiper tab.
Popup	Opens the URL in a native floating popup window.
Prompt	Shows a "Security & Routing" dialog asking you to choose Internal, Popup, or Safari for that link.
Safari	Opens the link externally in your default system browser.

Authentication Domains (OAuth Sign-In)

Many engines use third-party OAuth providers for logins (e.g., signing in to Claude or ChatGPT using a Google or Apple account). By default, WebKit restricts cookies and scripts to the engine's main domain, so clicking "Sign in with Google" can otherwise get blocked or bounced externally.

• The Solution: Add an Internal routing rule for the authentication domain so the login flow stays inside Quiper.
• Default Authenticator Expressions:
  • To allow Google Sign-In, add: ^https?://([^/]*\.)?accounts\.google\.com(/|$) → Internal
  • To allow Apple ID logins, add: ^https?://([^/]*\.)?appleid\.apple\.com(/|$) → Internal

Remembering Prompt Decisions

When a link triggers the Security & Routing prompt, you can check "Remember my choice for this domain" before choosing Internal, Popup, or Safari. Quiper then automatically inserts a new rule for that exact host at the top of the list so you won't be asked again. Press Escape or click Cancel to dismiss the prompt without navigating.

Migrating from older versions: Settings from versions prior to the unified routing editor (which used separate "Friend Domains" and "Associated Domains" lists) are automatically converted into equivalent Routing Rules the first time Quiper loads them.

Open Links in Quiper (External Link Handling)

Configured in the engine's URL editor (Settings ➔ Engines ➔ [Select Engine] ➔ URL), this section controls links that start outside Quiper: right-click any link in Safari, Mail, Finder, or another app and choose Open Link With ➔ Quiper. Quiper does not replace your default browser by itself — a plain open still goes to your default browser (or, if you make Quiper the default, see Quiper as the Default Browser); only links you hand to Quiper explicitly are affected.

• Enabled / Disabled: Turns the handler on for this engine. Enabling it seeds the domain list from the engine's own URL (query parameters dropped) if it is empty.
• Domains: Multiple entries, each a bare host (chatgpt.com) — a pasted URL works too, since the path, query, and port are stripped. A claim covers the domain and all of its subdomains (share.chatgpt.com matches chatgpt.com). When several engines claim the same domain, the first one in settings order wins; links claiming nothing open in your default browser as usual.
• Where Links Open:
  • New Session — the first of the engine's 10 session slots without an open page. If all 10 are open, Quiper asks which session the link should take over (its current page is replaced), defaulting to the least recently visited one.
  • Last Visited Session — the session you last used in this engine.
  • Fixed Session — one specific slot, picked from 1–9/0 (defaults to 0, the last slot).

Pinned Tabs engines open incoming links only in slots that have a tab URL; a fixed slot whose URL was removed falls back to opening a new session. An encrypted engine claims links only while it is unlocked: its claimed domains live inside its encrypted storage, so while it is locked a link claiming them opens as an unclaimed link does — in your fallback browser — instead of waiting, and unlocking restores its claims.

Quiper as the Default Browser

The General settings tab can make Quiper the system default web browser. Web links are then received by a small background helper installed with Quiper — it has no window or Dock icon, never appears in the app switcher, and shuts down when Quiper quits (macOS starts it again the moment a link needs it):

• Domains claimed by an engine are handed to Quiper and open there per that engine's Open Links in Quiper settings. An encrypted engine is claimed only while unlocked — while its volume is locked, its domains are hidden even from the helper, and such a link opens in the fallback browser like any other unclaimed link.
• Every other link opens directly in your fallback browser — the browser that was default right before Quiper, chosen explicitly in the same settings row, or Safari when neither is available — without bringing Quiper forward, so an unclaimed link never disturbs your app switcher order.

Choosing any other browser as the default (from Quiper's settings row or System Settings) returns links to that browser; Quiper then receives only links handed to it explicitly.

System Settings' Default web browser menu lists Quiper once; when two copies of Quiper are installed side by side — say a release and a nightly — the menu adds each one's version so they can be told apart. A development build appears as its own QuiperDev entry.

---

Web Data Isolation & Management

To prevent data leaks and maintain complete privacy, Quiper runs every engine in a fully sandboxed WebsiteDataStore container. This isolates cookies, SQLite databases, IndexedDB logs, and cache assets between your profiles.

Database Storage Paths

You can view the exact on-disk directory storing your engine's web profile by navigating to the Web Data sub-tab:

• Standard Storage (Unencrypted): The data resides in a dedicated sandboxed folder under application support: ~/Library/Application Support/app.sassanh.quiper.Quiper/WebKit/WebsiteData/<Engine-UUID>
• Secure Storage (Touch ID Encrypted): When Encrypt Local Storage is toggled on (see Touch ID & Security), Quiper dynamically mounts an AES-256 APFS sparsebundle over the WebKit folder at launch: /Volumes/quiper-secure-<Engine-UUID>

Show in Finder

Clicking Show in Finder opens the native macOS Finder directly at the location of the selected engine's database folder, allowing you to manually audit the local files or verify encryption states.

Reset Web Data

• Clicking Reset Web Data... prompts you to permanently purge all data associated with that specific engine.
• Purged Content: Cookies, Local Storage, Cache, Service Workers, Session Storage, and WebSQL databases.
• Result: Instantly logs you out of all sessions inside the engine and clears its cache footprint without affecting other engines.