简体中文 · Contributing · Install from source · Roadmap · Security
Native floating web workspaces for macOS — AppKit + WebKit, no Electron, and no special privacy permission for core use.
CornerFloat is an open-source, native macOS menu-bar utility that keeps interactive websites in resizable, always-on-top panels. It is designed for chat tools, mail, task references, and any page that should remain available while you work elsewhere.
CornerFloat is early-stage software. The current source preview is 0.8.0 (build 11), and saved-data formats or internal APIs may still evolve before 1.0. There is no public signed binary or GitHub Release yet; build the current preview from source.
CornerFloat does not yet offer a signed, one-click app download. GitHub's green
Code → Download ZIP button downloads the source code, not a finished
CornerFloat.app. You can still build and install a personal copy on a
supported Mac without an Apple developer account or administrator password.
- A Mac running macOS 14 or later.
- An internet connection for the first dependency download.
- Xcode 15 or later, or Apple's free Command Line Tools with Swift 5.9 or later.
- About 1 GB of free space for the source, dependency, and build cache.
If the developer tools are not already installed, open Terminal, run the following command, complete Apple's installation dialog, and then continue:
xcode-select --install- On this repository page, choose Code → Download ZIP.
- Open the downloaded ZIP to create a source folder, normally named
CornerFloat-main. - Open Terminal.
- Type
cd, including the space, drag that source folder into the Terminal window, and press Return. - Run these commands:
make bootstrap
make install
open "$HOME/Applications/CornerFloat.app"git clone https://github.com/kaichen-maker/CornerFloat.git
cd CornerFloat
make bootstrap
make install
open "$HOME/Applications/CornerFloat.app"make bootstrap checks the Mac and downloads the pinned Swift dependency.
make install builds CornerFloat for the current Mac, applies a local ad-hoc
signature, and installs it at ~/Applications/CornerFloat.app without sudo.
The first build can take several minutes. It is complete when Terminal prints
Installed CornerFloat at .../Applications/CornerFloat.app.
CornerFloat is a menu-bar app, so it normally has no Dock icon. After it opens,
look for the CornerFloat icon in the menu bar and use that menu to open ChatGPT,
another website, or a saved workspace. Choose Quit CornerFloat from the
same menu, or press Command-Q while CornerFloat is active, to exit completely.
The source-built copy includes the core panels, tabs, browsing, Quick Sites, favorites, and workspaces. It does not include the release-only automatic-update channel or Apple-approved cross-site passkey entitlement. Some OAuth providers may also require More → Open in Default Browser under their own policies.
Website voice and dictation work only on HTTPS pages. When a site requests the microphone—normally after you click its voice or microphone control—CornerFloat lets WebKit ask rather than granting access automatically. The first use can require two separate choices: respond to the macOS CornerFloat prompt and the requesting website's WebKit prompt in the order the system presents them. A camera request, including a combined camera-and-microphone request, is denied.
If the current input/output route risks Bluetooth two-way audio degradation, a CornerFloat explanation appears before the website's WebKit prompt. Choose Use Mac Microphone to switch the system default input temporarily when a built-in input is available, Continue with Bluetooth to leave the route unchanged, or Cancel to deny that request. Without a built-in alternative, the explanation offers only the latter two choices. A temporary switch occurs only after an explicit choice.
From the source folder, run the following commands to build and open a temporary
copy at dist/CornerFloat.app:
make bootstrap
make runFirst quit CornerFloat. If the saved library matters to you, export a backup from
Settings before updating this early preview. If you cloned with Git, return to
the CornerFloat folder and run:
git pull --ff-only
make bootstrap
make install
open "$HOME/Applications/CornerFloat.app"If you used Download ZIP, download the latest ZIP again, open the new source
folder, and repeat make bootstrap and make install.
To remove the installed app, first turn off Launch at Login in Settings and quit CornerFloat. Then run this from the source folder:
make uninstallThis preserves preferences, saved workspaces, and website sessions. If the
source folder is gone, open your home Applications folder in Finder and move
CornerFloat.app to the Trash instead.
If a command fails, read the first FAIL, error:, or fatal: line. The most
common causes are a Mac older than macOS 14, unfinished Command Line Tools
installation, or a failed first dependency download. If the app opens but no
window appears, check the macOS menu bar: CornerFloat is intentionally a
menu-bar app.
For troubleshooting and separate data-reset instructions, read the source-build guide.
This is a frame from a privacy-safe, real-time macOS capture—not a UI mockup. It shows the current native WebKit panel, integrated traffic lights and address bar, and the spacious resizable layout. The full 90-second recording is kept outside Git so a normal clone remains small; maintainers can follow the GitHub publishing guide to attach its public link here after the repository is online.
Both images come from the current local 0.8.0 source build. The normal product surface is a resizable always-on-top WebKit panel; these repository-safe views show the first-run explanation and the reusable native settings surface without including website account data.
Normal browser windows disappear behind the task at hand. CornerFloat keeps the websites you choose inside its own persistent WebKit panels so they remain available beside the rest of your work.
It is a standalone macOS application, not a browser extension or Stage Manager replacement.
- Native resizable AppKit panels with standard traffic lights and window edges.
- Configurable global show/hide shortcut (default
Shift-Command-Space) without Accessibility or Input Monitoring access. - Optional edge auto-hide, click-through, opacity, multiple displays, all Spaces, and full-screen auxiliary behavior.
- Smart address bar for URLs, named destinations, and Google search.
- Multiple browser tabs, persistent website sessions, upload/download, popups, JavaScript dialogs, secure website voice/dictation, and actionable failure states.
- A native Bluetooth voice preflight before website microphone capture, with explicit choices to use an available Mac microphone temporarily, keep Bluetooth unchanged, or cancel.
- Native Settings (
Command-,) for launch behavior, Launch at Login, edge auto-hide, conflict-safe global shortcut presets, and local data portability. - Favorites, recent destinations, and saved multi-panel workspaces.
- User-defined Quick Sites: map one or more address-bar words to any HTTP or HTTPS destination, then open it from the address bar or menu-bar menu.
- Native Liquid Glass on macOS 26 and system vibrancy on macOS 14-15.
- No CornerFloat account, ads, or analytics.
- Versioned JSON library export/import with preflight validation, confirmation, and atomic replacement; website cookies and sign-ins remain separate.
- Native by default: AppKit owns the menu bar and floating window behavior; WebKit supplies a system browser engine without bundling Electron or Chromium.
- Narrow permission boundary: normal browsing, workspaces, and the global show/hide shortcut request no Accessibility, Screen Recording, camera, or microphone access by themselves. An HTTPS site can request the microphone, but WebKit and macOS keep access behind user decisions; camera capture remains denied. A temporary system input switch is separately user-triggered and guarded against overwriting a later manual device change.
- Defensive browser behavior: unsafe address-bar schemes are blocked, external app launches require confirmation, and failed form submissions are never silently replayed.
- Data-safe boundaries: downloads stage beside their destination and replace it atomically only after WebKit reports success; transient authentication parameters are removed before URLs enter preferences or the local library.
- Durable local state: versioned decoding preserves compatible favorites, recents, Quick Sites, and web workspaces while retired window-mirroring entries are safely ignored. Libraries created by a newer schema open read-only before evolving nested records are decoded, avoiding accidental recovery rewrites.
- Layered verification: pure helper checks, real loopback-only
WKWebViewintegration tests, AppKit acceptance, lifecycle diagnostics, and release validators exercise different boundaries without overstating CI coverage. - Two-architecture release path: formal builds compile arm64 and x86_64 separately, combine them as Universal 2, and verify every app/Sparkle Mach-O.
Requirements:
- macOS 14 or later;
- Xcode or Apple Command Line Tools;
- Git, Swift Package Manager, Make, and Python 3.
git clone https://github.com/kaichen-maker/CornerFloat.git
cd CornerFloat
make bootstrap
make run
make checkThis contributor path opens the temporary development copy and runs the checks expected before a pull request. For a reusable personal installation, follow Install and use from source above. A Developer ID and notarization are needed only when a maintainer distributes a downloadable binary to other users; CornerFloat does not currently publish one.
Available commands:
make helpSee CONTRIBUTING.md before opening a pull request and docs/ARCHITECTURE.md before changing permissions, persistence, navigation, or updates.
CornerFloat is a menu-bar app and normally has no Dock icon. After launching, use the CornerFloat status item to open ChatGPT, another webpage, or a saved workspace.
Closing a red traffic-light button removes that panel. It does not terminate the
menu-bar process. Choose Quit CornerFloat from the menu or press Command-Q
while the app is active to exit completely.
| Action | Shortcut |
|---|---|
| Show or hide all panels globally | Shift-Command-Space by default; configurable in Settings |
| New ChatGPT panel | Command-N |
| Open another website | Shift-Command-N |
| New / close browser tab | Command-T / Command-W |
| Next / previous browser tab | Control-Tab / Control-Shift-Tab |
| Close the current panel | Shift-Command-W |
| Focus address bar | Command-L |
| Reload / back / forward | Command-R / Command-[ / Command-] |
| Favorite current page | Command-D |
| Save workspace | Option-Command-S |
| Open Windows & Library | Shift-Command-M |
| Open Settings | Command-, |
| Compact / standard / spacious panel | Option-Command-- / Option-Command-0 / Option-Command-+ |
| Quit CornerFloat | Command-Q |
| Capability | Permission | Why |
|---|---|---|
| Web panels, tabs, search, Quick Sites, favorites, workspaces | None | Content runs in CornerFloat's WebKit window |
| Global show/hide shortcut | None | Uses the macOS global hot-key API and does not read typed keys |
| Launch at Login | None | Uses the macOS Login Items service only after the user changes the Settings switch |
| Microphone requested by an HTTPS website | macOS Microphone access and that website's WebKit permission, on demand | Both decisions remain under the user; CornerFloat never grants access automatically |
| Website passkeys in an eligible signed release | Passkeys Access for Web Browsers, on demand | The menu appears only when the app contains the matching release provisioning profile |
CornerFloat denies website camera and combined camera-and-microphone requests. It does not automatically approve microphone access, record audio itself, or store or upload audio. After both permissions are granted, the HTTPS website you chose receives and handles microphone audio under its own privacy policy.
Before WebKit prompts on a risky Bluetooth input/output route, CornerFloat reads only the local device details needed for a voice-quality check and offers Use Mac Microphone, Continue with Bluetooth, or Cancel when a built-in input is available; otherwise it offers continue or cancel. Choosing the Mac microphone temporarily changes the system default input, so other audio apps can observe it during the session. When website capture ends, the panel closes, or CornerFloat quits, the app makes a best-effort restoration of the previous input only if the current input is still CornerFloat's temporary choice. CornerFloat also monitors default-input changes and relinquishes its temporary-route ownership when it detects a later user or app choice. Device choices are not persisted, and CornerFloat does not copy, analyze, store, or send microphone audio to a CornerFloat service.
Quick Sites, favorites, recents, and workspace layouts stay under the current macOS user's Application Support directory. Settings can export or import that library as inspectable JSON; WebKit manages site cookies and sessions separately and they are never included in the export.
Read PRIVACY.md for the complete policy.
For website voice or dictation, use the control on an HTTPS page. If access was previously denied, enable CornerFloat under System Settings → Privacy & Security → Microphone, reload the page, and review the website's own prompt or site settings. See SUPPORT.md for the complete recovery steps.
Apple explains that a Bluetooth headset used for both playback and microphone input switches from high-quality listening to lower-quality two-way audio; see If sound quality is reduced when using Bluetooth headphones with your Mac. CornerFloat avoids that switch only when the user explicitly chooses the Mac microphone. Continuing with Bluetooth deliberately preserves the current route.
Google prohibits OAuth authorization inside application-controlled embedded
browsers, and Microsoft or an organization may impose a similar restriction.
CornerFloat no longer preemptively cancels ChatGPT's Google redirect: WebKit may
attempt the flow in place with a truthful CornerFloat/<version> product token,
a visible URL, and native connection-security information. It neither claims to
be another browser nor rewrites authentication requests. Google may still reject
the session under its policy; More → Open in Default Browser remains the
supported fallback, and browser cookies are not copied back into CornerFloat.
Passkey support also depends on the site, account, macOS, WebKit, and a public build signed with an Apple-approved Web Browser Public Key Credential managed entitlement. An ad-hoc development build can test CornerFloat's authorization logic but is not an end-to-end cross-site passkey acceptance artifact.
flowchart LR
Entry["Menu bar and global hot key"] --> App["App lifecycle and panel registry"]
App --> Panels["Resizable AppKit floating panels"]
Panels --> Browser["Persistent WKWebView tabs"]
Browser --> Web["HTTP and HTTPS websites"]
App --> Library["Quick Sites, favorites, recents, workspaces"]
Library --> Disk["Versioned Application Support JSON"]
Library --> Portable["Validated export and import"]
App -. eligible release only .-> Updates["Signed Sparkle updates and Passkey review"]
The diagram shows ownership rather than every callback. Read the architecture guide for navigation, persistence, and release trust boundaries, and the window-mirroring decision record for the product and permission trade-off behind the current web-only scope.
Sources/CornerFloat/ AppKit, WebKit, persistence, and update code
Tests/ Focused helper and real local WebKit integration tests
Resources/ Info.plist, icon, privacy and support pages
scripts/ Build, test, package, diagnostics, and release validation
docs/ Architecture, roadmap, lifecycle, and release guidance
.github/ CI and contribution templates
The only Swift package dependency is pinned to Sparkle 2.9.4. Third-party terms are listed in THIRD_PARTY_NOTICES.md.
make test is the reproducible contributor suite. make check also compiles
with complete Swift concurrency checking and warnings as errors. make acceptance additionally
opens AppKit windows and exercises the global shortcut and lifecycle diagnostics
from a logged-in desktop.
Physical display changes, system sleep, account sign-in, website microphone capture, passkeys, Developer ID signing, notarization, and update installation require the manual evidence described in docs/RELEASE_CHECKLIST.md.
No public binary has been released yet. The optional public-release path requires the maintainer's Apple and Sparkle credentials. Forks can build and modify the app freely under MIT, but must use their own bundle identity, signing certificate, update keys, and download feed before distributing binaries. A provisioning profile is required only when a fork opts into an Apple-approved managed entitlement such as the optional cross-site Passkey capability.
- Click-through makes a whole panel ignore the pointer until disabled from the menu-bar menu.
- Reduced Transparency replaces glass with a clearer system background.
The project uses a maintainer-led governance model. Focused contributions are welcome; see GOVERNANCE.md, the Code of Conduct, and the public roadmap.
CornerFloat source code is available under the MIT License. Sparkle and its bundled components retain their own license notices.