[macOS] Keep quick-access-terminal on top of all Desktop / Spaces

[yougotwill]

Is your feature request related to a problem? Please describe.
When using the quick access terminal and toggling it via a shortcut, if I move between spaces sometimes it gets stuck on a desktop (e.g. Desktop 2). Then if I move to Desktop 3 when I trigger the shortcut to display the quick window it's doesn't appear but if I switch back to Desktop 2 then it appears correctly.

Describe the solution you'd like
The quick-access-window should always be set to the current Desktop e.g. the Always on Top macOS setting.

Describe alternatives you've considered
When we close the quick-access-terminal make sure it isn't associated with a preexisting Space or Desktop.

Additional context

Video

Kapture.2025-06-20.at.13.49.12.mp4

[kovidgoyal]

Doesnt reproduce for me on my macOS machine. Can you post an exact set
of steps to reproduce it.

[kovidgoyal]

no follwup

[si14]

@kovidgoyal I just had a similar issue with the quick access terminal and it went away after a full reset. I suspect it's a macOS bug, because the behaviour is similar to what I saw previously with a home-brewed quick access Kitty.

I was using Kitty for years running a "quick window" with Hammerspoon (just hiding and showing the window on keypress). To work well, the window needs to be "assigned to all desktops" in the tray. However, once a week or two the status seemed to silently be reset, and my quick terminal key started to send me to one of the spaces where Kitty resides. The tick in the right click menu would be at "All Desktops", but the window would behave normally, as if that tick was set to "None". Toggling it back and forth solved the issue for another week.

I don't know, but I suspect that you're using the same API that the tick in the tray is using and it might be triggering the same macOS bug. If that's the case, Kitty might be able to work around it by resetting that value periodically.

[kovidgoyal]

It's a simple single function that sets it up, see
_glfwPlatformSetLayerShellConfig
in glfw/cocoa_window.m

There isnt any "join all desktops" but what it does do is set
collection behavior to:
NSWindowCollectionBehaviorCanJoinAllSpaces

Unfortunately, without being able to reproduce, when using an opaque and
poorly documented API like cocoa its almost impossible to fix, since one
cant reverse engineer the coca internal behavior without a reproducer.

There's no other spaces related code except to focus the last active os
window on os window close, see cocoa_focus_last_window() but that code
path isnt involved here since the quick access window is hidden not
closed.

[si14]

Thank you for the explanation!

I agree, I haven't figured out how to reproduce this bug. It's real though, I encountered it on two different macbooks. My hope is that if you encounter it yourself, my report might be useful.

In terms of the API you mentioned, my hypothesis is that sometimes the NSWindowCollectionBehaviorCanJoinAllSpaces flag is spontaneously reset. Also, this issue ahkohd/tauri-nspanel#76 looks remarkably similar.

[kovidgoyal]

That flag is re-applied everytime the function is called and the function is called everytime the iwndow is shown, so not sure what more kitty could do here.

[yougotwill]

Doesnt reproduce for me on my macOS machine. Can you post an exact set of steps to reproduce it.

@kovidgoyal Sorry for the slow reply. Life happened. I have found a reproducible case. Please make sure you have at least 2 Spaces setup up beforehand.

1. Open any application on Space 1.
2. Activate the quick-access-terminal.
3. Close the quick-access-terminal (not exit just hide it).
4. Enter Full Screen for the open application (this will create a temporary 3rd space).
5. Exit Full Screen for the open application.
6. Move to Space 2.
7. Activate the quick-access-terminal.

You will not see the quick-access-terminal on Space 2 but if you move to Space 1 you will see it was activated. I wonder if it is an indexing issue with the Spaces caused by the temporary 3rd space.

[yougotwill]

Have confirmed it's definitely full screening an application that causes this bug. Because when it turned off hide_on_focus_loss everything worked perfectly until I went full screen, returned and changed spaces before opening the quick access terminal again.

[kovidgoyal]

OK I will try to reproduce when I next have a moment.

[si14]

It's almost a year later, and the quick access window seems to work perfectly now. @kovidgoyal thank you for all of your hard work on Kitty and relentless bug hunting, it's by far the best terminal out there.

[kovidgoyal]

You are welcome!