{"id":31692557,"url":"https://github.com/sassanh/quiper","last_synced_at":"2026-05-29T02:01:53.273Z","repository":{"id":313737641,"uuid":"1052457921","full_name":"sassanh/quiper","owner":"sassanh","description":"A macOS app providing a system-wide overlay for AI services like Gemini, Claude, ChatGPT and Grok. Access multiple chat instances with global hotkeys, switch engines, and customize engines.","archived":false,"fork":false,"pushed_at":"2026-05-27T15:20:00.000Z","size":2600,"stargazers_count":21,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-27T15:25:52.533Z","etag":null,"topics":["browser","chatbot","chatgpt","gemini","grok","llm","macos","overlay","vibecoding"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sassanh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"Supporting/Info.plist","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-08T04:49:46.000Z","updated_at":"2026-05-27T15:21:22.000Z","dependencies_parsed_at":"2025-09-08T07:08:55.505Z","dependency_job_id":null,"html_url":"https://github.com/sassanh/quiper","commit_stats":null,"previous_names":["sassanh/quiper"],"tags_count":51,"template":false,"template_full_name":null,"purl":"pkg:github/sassanh/quiper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sassanh%2Fquiper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sassanh%2Fquiper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sassanh%2Fquiper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sassanh%2Fquiper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sassanh","download_url":"https://codeload.github.com/sassanh/quiper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sassanh%2Fquiper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33633468,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser","chatbot","chatgpt","gemini","grok","llm","macos","overlay","vibecoding"],"created_at":"2025-10-08T14:53:57.687Z","updated_at":"2026-05-29T02:01:53.250Z","avatar_url":"https://github.com/sassanh.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Quiper\n\nQuiper is a macOS status-bar app that keeps your AI chat services in a single floating window. A global hotkey reveals the overlay, every service gets ten pre-created WebKit tabs, and the app stays out of the Dock so you can drop into an AI convo and return to work without re-arranging windows.\n\n![Quiper Main Window](.github/assets/hero.webp)\n\n[![CI](https://github.com/sassanh/quiper/actions/workflows/integration_delivery.yml/badge.svg)](https://github.com/sassanh/quiper/actions/workflows/integration_delivery.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub release](https://img.shields.io/github/v/release/sassanh/quiper.svg)](https://github.com/sassanh/quiper/releases)\n[![codecov](https://codecov.io/gh/sassanh/quiper/branch/main/graph/badge.svg)](https://codecov.io/gh/sassanh/quiper)\n\n## Highlights\n\n- **Overlay built for AI sites** – Define any site that works in Safari (Gemini, Claude, Grok, ChatGPT, Open WebUI, internal tools, etc.). Quiper opens each one inside its own `WKWebView` stack so session switches are instant.\n- **Keyboard first** – The default global shortcut is `⌥ Space`, but you can record any combination.\n- **Persistent sessions** – Each service owns ten live `WKWebView`s. They keep scrollback and form contents, while cookies/cache live in the shared WebKit store so authentication survives next launch.\n- **Notification bridge** – A JavaScript shim mirrors the browser `Notification` API into `UNUserNotificationCenter`.\n\n\u003cdetails\u003e\n\u003csummary\u003e📸 \u003cstrong\u003eGallery: Supported Engines\u003c/strong\u003e\u003c/summary\u003e\n\n\u003cp float=\"left\"\u003e\n  \u003cimg src=\".github/assets/main_chatgpt.webp\" width=\"49%\" /\u003e\n  \u003cimg src=\".github/assets/main_grok.webp\" width=\"49%\" /\u003e\n\u003c/p\u003e\n\u003cp float=\"left\"\u003e\n  \u003cimg src=\".github/assets/main_gemini.webp\" width=\"49%\" /\u003e\n  \u003cimg src=\".github/assets/main_google.webp\" width=\"49%\" /\u003e\n\u003c/p\u003e\n\u003cp float=\"left\"\u003e\n  \u003cimg src=\".github/assets/main_open-webui.webp\" width=\"49%\" /\u003e\n  \u003cimg src=\".github/assets/main_x.webp\" width=\"49%\" /\u003e\n\u003c/p\u003e\n\n\u003c/details\u003e\n\n## Installation\n\n**Requirements**: macOS 14.0+ (Sonoma), Apple silicon or Intel.\n\n### Download a release\n\n1. Download the latest `.app` from the [Releases](https://github.com/sassanh/quiper/releases/latest) page — direct download: [`Quiper.app.zip`](https://github.com/sassanh/quiper/releases/latest/download/Quiper.app.zip).\n2. Move `Quiper.app` to `/Applications`.\n3. Because this project isn't signed or notarized (Apple requires a paid Developer ID for that), Gatekeeper will block the first launch. Open **Settings → Privacy \u0026 Security** and click **Open Anyway** next to Quiper.\n4. Relaunch `Quiper.app`, click **Open** on the follow-up dialog, and macOS will remember that exception for this bundle path.\n5. Approve the notification prompt if you plan to use browser banners.\n\n\u003e If you rebuild, rename, or move `Quiper.app`, Gatekeeper treats it as a new binary, so repeat steps 3–4 after each update.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eUpdate Settings\u003c/strong\u003e\u003c/summary\u003e\n\nConfiguring automatic checks and downloads:\n\n![Update Settings](.github/assets/settings_updates.webp)\n\u003c/details\u003e\n\n#### Build provenance\n\nEvery release `.zip` is built entirely by [GitHub Actions](https://github.com/sassanh/quiper/actions/workflows/integration_delivery.yml) — no builds are produced on a developer's local machine and uploaded manually. This means you can inspect the exact steps that produced the binary by looking at the [workflow file](https://github.com/sassanh/quiper/blob/main/.github/workflows/integration_delivery.yml) in the repository.\n\nOn top of that, each build is stamped with a **[build provenance attestation](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds)**. Think of it as a tamper-evident seal: GitHub Signs a record that says *\"this exact file was produced by this exact workflow run, triggered from this exact commit.\"* The signature is stored publicly on GitHub's transparency log, so anyone can verify it — without trusting anything you say.\n\nIf you have the [GitHub CLI](https://cli.github.com/) installed, you can verify any release zip before running it:\n\n```bash\ngh attestation verify Quiper.app.zip --repo sassanh/quiper\n```\n\nA passing result confirms the file came from this repository's CI and hasn't been tampered with since it was built. A failure means the file should not be trusted.\n\n### Build from source\n\n```bash\ngit clone https://github.com/sassanh/quiper.git\ncd quiper\nopen Quiper.xcodeproj # Opens in Xcode\n# Press Cmd+R to build and run\n```\n\nCreate a distributable bundle:\n\n```bash\n./build-app.sh # Builds with xcodebuild, creates Quiper.app\nopen Quiper.app\n```\n\n## Daily Workflow\n\n### Global hotkey\n\n- Default `⌥ Space` toggles the overlay above every desktop.\n- Capture a new combo via Status menu → **Set New Hotkey**. The selection is saved into `~/Library/Application Support/Quiper/settings.json` under the `hotkey` key and re-registered immediately.\n\n### Inside the overlay\n\n| Action | Shortcut |\n| --- | --- |\n| Switch session 1–9 | `⌘ 1` … `⌘ 9` |\n| Session 10 | `⌘ 0` |\n| Switch service 1–9 | `⌘ ⌃ 1` … `⌘ ⌃ 9` (or `⌘ ⌥` + digit) |\n| Open Settings | `⌘ ,` |\n| Toggle Web Inspector | `⌘ ⌥ I` |\n| Hide overlay | `⌘ H` |\n| Find in page | `⌘ F` |\n| Zoom in/out | `⌘ +` / `⌘ -` |\n\nDismissing the window via shortcut or menu simply hides it; Quiper reactivates the previously focused app automatically.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eShortcut Configuration\u003c/strong\u003e\u003c/summary\u003e\n\nCustomize global and in-app shortcuts:\n\n![Shortcuts Settings](.github/assets/settings_shortcuts.webp)\n\u003c/details\u003e\n\n### Status-bar menu\n\n- Show / Hide Quiper\n- Settings window\n- Show / Hide Inspector (reflects the active state)\n- Clear Web Cache (purges `WKWebsiteDataStore.default()`)\n- Set New Hotkey\n- Install at Login / Uninstall from Login\n- Quit\n\n## Appearance\n\nQuiper supports per-theme window customization:\n\n- **Color Scheme**: Force Light or Dark mode, or follow System preference.\n- **Window Background**: Choose blur effect (with material options) or solid color.\n- **Per-Theme Settings**: When using System mode, configure light and dark themes separately.\n\n\u003cp float=\"left\"\u003e\n  \u003cimg src=\".github/assets/settings_appearance.webp\" width=\"49%\" /\u003e\n\u003c/p\u003e\n\n## Customization\n\n- **Services** – Drag services directly in the header segmented control or open Settings → Engines to add/delete/reorder entries. Each service includes a CSS selector used to focus the correct input field when the session becomes visible.\n- **Custom CSS** – Inject custom CSS per-engine for transparent backgrounds or style overrides.\n- **Custom Actions** – Define JavaScript snippets triggered by global or app-specific shortcuts to automate tasks (e.g., clicking 'New Chat' or scraping content).\n- **Manual edits** – All preferences live at `~/Library/Application Support/Quiper/settings.json`. Edit while Quiper is closed.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eExpanded Selectors\u003c/strong\u003e\u003c/summary\u003e\n\nShow full service details and conversation context:\n\n![Expanded Selectors](.github/assets/feature_selectors.webp)\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eService Configuration\u003c/strong\u003e\u003c/summary\u003e\n\nManage engines and custom actions:\n\n![Engine Settings](.github/assets/settings_engines.webp)\n\nDefine hotkeys for specific services:\n\n![Service Hotkeys](.github/assets/settings_shortcuts_hotkeys.webp)\n\u003c/details\u003e\n\n## Technical Details\n\n### Sessions and Storage\n\n- Each service entry in `settings.json` spawns ten `WKWebView`s during startup. Quiper hides all but the active view, so switching is instantaneous.\n- WebKit data (cookies, local storage, cache) is shared. Logging out of a service in one session signs out the others.\n- The default services (Gemini, Claude, Grok, ChatGPT, Open WebUI) live in `Settings.shared.defaultEngines`.\n\n### Notifications\n\n- `WebNotificationBridge` installs a user script that patches `Notification`, `Notification.requestPermission`, and `navigator.permissions.query` to match Safari's behavior.\n- When a site issues `new Notification(...)`, Quiper builds a `UNNotificationRequest` with the service URL, display name, and session index stored in `userInfo`.\n- `NotificationDispatcher` implements `UNUserNotificationCenterDelegate`; clicking a banner brings Quiper to the front, selects the recorded service, and activates the session before focusing the input field.\n\n## Reset \u0026 Data Paths\n\n| Item | Path | Notes |\n| --- | --- | --- |\n| Settings | `~/Library/Application Support/Quiper/settings.json` | JSON object; edit while Quiper is closed. |\n| LaunchAgent | `~/Library/LaunchAgents/com.\u003cusername\u003e.quiper.plist` | Created/removed via Install at Login. |\n| Downloads | `~/Downloads/` | Files initiated inside Quiper are saved here. |\n\nHit **Clear Web Cache** in the status menu to wipe cookies/cache without touching the JSON. For a full reset, quit Quiper and delete the settings file.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eGeneral \u0026 Danger Zone\u003c/strong\u003e\u003c/summary\u003e\n\nReset options and general configuration:\n\n![General Settings](.github/assets/settings_general.webp)\n\u003c/details\u003e\n\n## Troubleshooting\n\n- **Global hotkey fails** – Capture a new one so Quiper overwrites the `hotkey` entry in `settings.json`.\n- **Notifications never appear** – Use the status menu to open macOS notification settings and ensure alerts are allowed.\n- **Web view stuck or stale** – Use **Clear Web Cache** or reload the service.\n- **Build errors** – Ensure Xcode 16+ CLT are installed (`xcode-select --install`).\n\n## Contributing\n\n1. Fork the repository and branch from `main` (`feat/\u003ctopic\u003e`).\n2. Run `swift build` before opening a pull request.\n3. Include macOS version, Quiper build hash, repro steps, and screenshots for UI changes.\n\n## Versioning\n\nQuiper follows **[Pride Versioning](https://pridever.org/)** (PrideVer). This means we release when we are genuinely proud of the progress and quality, and our version numbers reflect our sentiment toward each release. Since Quiper is an end-user desktop application and not a library, this human-centric approach allows us to prioritize architectural integrity and user experience over rigid semantic constraints.\n\n### Update Channels\n\nIn addition to stable releases, Quiper provides two pre-production channels for testing:\n\n- **Nightly**: Automatically generated every day at midnight (UTC) from the latest code in the `main` branch. These builds are experimental and intended for developers or those who want the absolute latest features.\n- **Beta**: Manually triggered pre-releases used to validate specific features before they are merged into a stable version.\n\nBoth pre-production channels use the GitHub Actions **Run Number** as an internal build identifier. This ensures that the app can reliably detect updates even if the version string remains the same. Pre-production builds are explicitly marked with a `-nonproduction` suffix in their version string (e.g., `2.1.0-nightly-nonproduction`).\n\nYou can opt-in to these channels in **Settings → Updates**.\n\n## License\n\nQuiper is released under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsassanh%2Fquiper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsassanh%2Fquiper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsassanh%2Fquiper/lists"}