8000 GitHub - andhikapraa/topsy: Float a live, view-only mirror of any macOS window above everything — even fullscreen, across Spaces. ScreenCaptureKit. macOS 14+. · GitHub
[go: up one dir, main page]

Skip to content
andhikapraaPublic

About

Float a live, view-only mirror of any macOS window above everything — even fullscreen, across Spaces. ScreenCaptureKit. macOS 14+.

Topics

Resources

Code of conduct

Contributing

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

Topsy icon

Topsy

Keep any macOS window on top — even above fullscreen, across Spaces.

Building · Architecture · Contributing · Changelog

Topsy window picker

What it is

Topsy floats a live mirror of any single window above everything else, so you can keep a video call, a doc, or a terminal visible while you work in another app — including while that other app is fullscreen on a different Space.

It's a small, focused, view-only utility: the mirror is a live picture you watch, not a window you click into.

  • Works above fullscreen — the mirror floats over YouTube, Xcode, or Keynote in fullscreen on any Space.
  • Pin a specific window — choose the exact window from a live thumbnail grid, including a window that shares a process with others (e.g. a WhatsApp call window, separate from the main WhatsApp window).
  • Auto-refreshing picker — the grid updates about once a second while open, so a newly-opened window shows up without a manual refresh.
  • Never steals focus — the app you're working in stays key. The mirror tracks the source window's size/aspect as it changes.

Why a mirror (and why view-only)

macOS doesn't let one app reorder another app's windows — the Window Server enforces this. The only way to put an arbitrary window "always on top" with public APIs is to capture its pixels and draw them in a window you own. Forwarding clicks/keystrokes back through that mirror was prototyped and abandoned: it can't be done with public, non-focus-stealing APIs. The full story is in ARCHITECTURE.md and docs/dev/HANDOFF.md §7.

Requirements

  • macOS 14.0 or later
  • Xcode 16+ to build (no notarized release yet — build from source)

Install

There's no signed release yet, so build it yourself — it's quick. Full steps, including the one-time self-signed certificate, are in BUILDING.md. In short:

git clone https://github.com/andhikapraa/topsy.git
cd topsy
# create the "Topsy Dev" signing cert once — see BUILDING.md
open Topsy.xcodeproj   # ⌘R to run

On first launch macOS prompts for Screen Recording — that's the only permission Topsy needs (it's what ScreenCaptureKit uses to capture pixels). No Accessibility, no Input Monitoring.

Usage

  1. Launch Topsy — the Pin a Window picker appears.
  2. Click any window's thumbnail to float a live mirror of it.
  3. Drag the mirror anywhere; it stays on top across Spaces and fullscreen.
  4. Close the mirror (hover → ✕) or press the global hotkey to return to the picker. Set the hotkey in Settings (⌘,).

Status

Early development, view-only and intentionally so. The window-level picker, ~1s auto-refresh, system-window filtering, and the floating aspect-tracking mirror all work. See CHANGELOG.md for what's landed and ARCHITECTURE.md for how it works.

Contributing

Issues and PRs welcome — please read CONTRIBUTING.md first (especially the note on why input forwarding is out of scope).

License

MIT. Topsy is a ground-up rewrite of itsabhishekolkha/AlwaysOnTop; see CREDITS.md for attribution.

About

Float a live, view-only mirror of any macOS window above everything — even fullscreen, across Spaces. ScreenCaptureKit. macOS 14+.

Topics

Resources

Code of conduct

Contributing

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0