macOS: toggle_visibility global keybinding doesn't work when Ghostty is focused

[mac0ne]

Issue Description

When using a global keybinding for toggle_visibility (e.g. global:cmd+escape), the keybinding only works to show Ghostty when it is hidden/unfocused, but does not work to hide Ghostty when it is currently focused. This effectively makes the toggle one-directional.

The root cause is a gap in key event handling between the GlobalEventTap and the local event handler in AppDelegate:

1. GlobalEventTap (GlobalEventTap.swift:134) skips all key processing when NSApp.isActive is true, assuming the local event handler will take care of it.
2. The local event handler (AppDelegate.swift:709) exits early when NSApp.mainWindow != nil, assuming the window/surface key handling chain will process it.
3. The surface key event chain processes the key as terminal input, not as a global app-level action.

This means global-scope keybindings like toggle_visibility fall through all three paths without being handled when Ghostty is focused.

I have a working fix at: https://github.com/mac0ne/ghostty/tree/fix/global-keybinds-macos
commit: 948f583

Expected Behavior

Pressing the configured global keybinding (e.g. cmd+escape) should toggle Ghostty's visibility regardless of whether Ghostty is currently focused or not.

Actual Behavior

The keybinding only activates Ghostty when it is hidden/unfocused. Pressing the same keybinding while Ghostty is focused does nothing — the app remains visible.

Reproduction Steps

1. Add a global keybinding for toggle_visibility in your config, e.g.:

   keybind = global:cmd+escape=toggle_visibility
   

2. Launch Ghostty
3. Switch to another application so Ghostty is not focused
4. Press cmd+escape — Ghostty appears and gains focus (works correctly)
5. Press cmd+escape again — nothing happens (expected: Ghostty should hide)

Ghostty Logs

When pressing the keybinding while Ghostty is focused, the debug log shows no `toggle_visibility` dispatch. When pressing while unfocused, the log shows:


debug(embedded_window): dispatching action target=app action=.toggle_visibility value=void

### Ghostty Version

```text
Ghostty 1.3.0-main+055ed2858

Version
  - version: 1.3.0-main+055ed2858
  - channel: tip
Build Config
  - Zig version   : 0.15.2
  - build mode    : .ReleaseFast
  - app runtime   : .none
  - font engine   : .coretext
  - renderer      : renderer.generic.Renderer(renderer.Metal)
  - libxev        : kqueue

OS Version Information

macOS 26.3.1

(Linux only) Display Server

None

(Linux only) Desktop Environment/Window Manager

No response

Minimal Ghostty Configuration

keybind = global:cmd+escape=toggle_visibility

Additional Relevant Configuration

This issue is macOS-only. The Linux/GTK implementation uses the XDG Desktop Portal GlobalShortcuts interface, where the desktop environment handles key interception and delivers activation signals regardless of app focus state.

I acknowledge that:

• I have reviewed the FAQ and confirm that my issue is NOT among them.
• I have searched the Ghostty repository (both open and closed Discussions and Issues) and confirm this is not a duplicate of an existing issue or discussion.
• I have checked the "Preview" tab on all text fields to ensure that everything looks right, and have wrapped all configuration and code in code blocks with a group of three backticks (```) on separate lines.

[seanmozeik]

This also breaks window managers like aerospace, which don't receive global commands when ghostty is focused. I'd be super grateful if this gets into 1.3.1!

[bo2themax]

It works fine for me

Screen.Recording.2026-03-23.at.18.45.03.mp4

[mac0ne]

it's been weeks long and I can't reproduce this either. But when trying another issue came out:

Screen.Recording.2026-03-24.at.02.50.39.mov

The recording shows that the global keybinding doesn't work when Ghostty is NOT focused.

my build with the fix mentioned works, though theoretically my fix is irrelevant:

Screen.Recording.2026-03-24.at.03.09.12.mov

Just for reference in case someone else encounter this issue.

[mac0ne]

above issue just occurred again even with the build with that fix. It's happening randomly. When I retried the issue disappeared.

[mac0ne]

it turned out to be an issue with macOS application permissions. Deleting the application and removing relevant permission records in Settings-> Privacy&Security->Accessibility resolved the issue with global keybinding when Ghostty is NOT focused.

[bo2themax]

it turned out to be an issue with macOS application permissions. Deleting the application and removing relevant permission records in Settings-> Privacy&Security->Accessibility resolved the issue with global keybinding when Ghostty is NOT focused.

It would be great if you could update the discussion description. This way we can follow up and someone might find a way to consistently reproduce the issue so we can fix it.