Managing Engines

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

---

Service 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 at the bottom of the list.
3. Each engine exposes the following properties:
   • Name: The label displayed in the switcher tab (e.g., "ChatGPT").
   • URL: The target web address (e.g., https://chatgpt.com).
   • Focus Selector: The CSS selector identifying the prompt input field.
   • Custom CSS: Overrides to style the web elements (see the Custom CSS Injection section below).
   • Friend Domains: Auxiliary URLs required for authentication.
   • Activation Shortcut: A dedicated hotkey that summons the window and immediately opens this engine.

---

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).

---

Focus 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 Focus Selector

If you add a custom web service 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 Focus Selector field in settings.

Default Selectors for Common Services

Service	Focus Selector
Gemini	.textarea
Claude	div[contenteditable='true']
Grok	textarea[aria-label='Ask Grok anything'],div[contenteditable=true]
ChatGPT	#prompt-textarea
X (Grok)	div[contenteditable='true']
Open WebUI	#chat-input[contenteditable='true']

---

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.

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 service 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 Focus 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.

---

Friend Domains & Authentication

Many AI services use third-party OAuth providers for logins (e.g., signing in to Claude or ChatGPT using a Google or Apple account).

• The Sandboxing Isolation: By default, WebKit restricts cookies and scripts to the engine’s main domain to protect security. If you click "Sign in with Google," WebKit might block the authentication flow.
• The Solution: Add authentication domains to the Friend Domains list in the engine settings.
• Default Authenticator Expressions:
  • To allow Google Sign-In, add: ^https?://([^/]*\.)?accounts\.google\.com(/|$)
  • To allow Apple ID logins, add: ^https?://([^/]*\.)?appleid\.apple\.com(/|$)
  • These regular expressions tell Quiper to trust these domains for cookie sharing and script execution during the login process.

---

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.