This is an update to address common agentic issues I run into,
but the `build.nu` script may be generally helpful to people using
the Nix env since `xcodebuild` is broken by default in Nix due to the
compiler/linker overrides Nix shell does.
## Summary
This extends the macOS bell implementation to support the `audio` bell
feature, bringing it to parity with GTK/Linux.
Previously, macOS only had the `system` feature (`NSSound.beep()`). This
PR adds:
- **`audio` bell feature on macOS**: plays the file at `bell-audio-path`
using `NSSound(contentsOfFile:)`, respecting `bell-audio-volume`
- **`cval()` on the `Path` type**: allows `Path` values (a union type)
to be returned through the C API, which is needed for Swift to read
`bell-audio-path`
- **Removes `(GTK only)` restriction** from `bell-audio-path` and
`bell-audio-volume` documentation
## How it works
In `AppDelegate.swift`, when the bell rings and the `audio` feature is
enabled, Ghostty now:
1. Reads `bell-audio-path` from config
2. Loads it as an `NSSound`
3. Applies `bell-audio-volume` and plays it
Falls back gracefully if the path is not set or the file cannot be
loaded.
## Example config
```
bell-features = audio
bell-audio-path = /System/Library/Sounds/Glass.aiff
bell-audio-volume = 0.8
```
## Testing
- Set `bell-features = audio` and `bell-audio-path` to any valid audio
file
- Trigger a bell with `echo -e '\a'`
- Audio should play at the configured volume
Extends the macOS bell implementation to support the `audio` bell
feature by playing a user-specified audio file via NSSound.
Previously, macOS only supported the `system` feature (NSSound.beep()).
This change adds support for:
- `audio` bell feature: plays the file at `bell-audio-path` using
NSSound, respecting the `bell-audio-volume` setting
- Adds `cval()` to the `Path` type so it can be returned via the C API
Also removes the "(GTK only)" restriction from `bell-audio-path` and
`bell-audio-volume` documentation, as these options now work on macOS.
Example config:
bell-features = audio
bell-audio-path = /System/Library/Sounds/Glass.aiff
bell-audio-volume = 0.8
This fixes two overlapping issues regarding window positioning and Cmd+W window closures on macOS:
1. `window-position-x` and `window-position-y` coordinates were being ignored on initial launch because `TerminalWindow.setInitialWindowPosition` depended on the `TerminalController`, which isn't fully attached during `awakeFromNib`. This logic was moved so explicit coordinates are correctly enforced.
2. When closing a window via Cmd+W (leaving the app active), reopening the window would continuously cascade down and to the right rather than restoring to the previous position. It now checks if there are other windows open before cascading.
3. `LastWindowPosition` was updated to save both the frame origin and size (width/height), ensuring that restoring a closed window correctly mimics native AppKit State Restoration size behaviors while honoring explicit configurations.
Depends on #11030
- Update constraints of `TerminalGlassView`
- Use `TerminalViewContainer.DerivedConfig` to map styling properties
- Add TerminalViewContainerTests
- Instead of using delay, now the view updates are explicitly called by
window controllers
* ensure that `ghostty.h` compiles during basic Zig tests
* ensure that non-exhaustive enums are kept synchronized between
`ghostty.h` and their respective Zig counterpart.
* adjust some enums that varied from established conventions
Fixes#11029 (probably)
If you renamed the app bundle, the prior check would infinite loop due
to the combination of two bugs: invalid termination checks and
hardcoding "Ghostty.app"
Fixes#10935
This is a more robust way to detect "is my surface focused" because that
question usually means "is my surface the last focused surface" if a
_different_ surface is not focused. We already have used this pattern
all over but we should extend it to SwiftUI too.
**Summary:**
- Add tint overlay to dim terminal windows when inactive, fixes
https://github.com/ghostty-org/ghostty/discussions/10040
- Refactor the liquid glass effect into a dedicated `TerminalGlassView`
class
Note: The tint overlay color and opacity values may not be ideal —
feedback is welcome.
**AI Disclosure:** I used Claude Code to read the macos repo and
understand the liquid glass implementation. Implemented basic tint
overlay mainly by hand. Refactor the code and review changes with Claude
Code.
It was introduced in 2a81d8cd2910b12fe007f0bc5fb5d6be57f0f0fe[0]. We
lost the subview. prefix of from the contains() call.
Co-authored-by: Brent Schroeter <github@brentsch.com>
Fixes: https://github.com/ghostty-org/ghostty/issues/10923
Link: 2a81d8cd29 [0]
## Summary
Cmd-clicking a file path containing `~` (e.g. `~/Documents/file.txt`)
fails to open the file on macOS because `URL(filePath:)` treats `~` as a
literal directory name rather than the user's home directory.
This uses `NSString.expandingTildeInPath` to resolve `~` before
constructing the file URL.
## Root Cause
In `openURL()`, when the URL string has no scheme it falls through to:
```swift
url = URL(filePath: action.url)
```
Swift's `URL(filePath:)` does not perform tilde expansion. A path like
`~/Documents/file.txt` produces a URL pointing to a non-existent file,
and `NSWorkspace.open` silently fails.
## Fix
```swift
let expandedPath = NSString(string: action.url).expandingTildeInPath
url = URL(filePath: expandedPath)
```
## Reproduction
1. Have a terminal application (e.g. Claude Code) that outputs file
paths with `~` prefixes
2. Cmd-click the path in Ghostty on macOS
3. The file does not open (fails silently)
With this fix, the path resolves correctly and opens in the default
editor.
`URL(filePath:)` treats `~` as a literal directory name, so
cmd-clicking a path like `~/Documents/file.txt` would fail to
open because the resulting file URL doesn't point to a real file.
Use `NSString.expandingTildeInPath` to resolve `~` to the user's
home directory before constructing the file URL.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This rule is generally trying to be helpful, but it doesn't like a few
places in our code base where we're intentionally listing out all of the
well-known cases. Given that, just disable it.
https://realm.github.io/SwiftLint/no_fallthrough_only.html
Addresses discussion in #3729 and issues relating to #7333, #9590, and
#9617.
Rendering the Secure Keyboard Input overlay using innerShadow() can
strain the resources of the main thread, leading to elevated CPU load
and in some cases extended disruptions to the main thread's
DispatchQueue that result in lag or frozen frames. This change achieves
the same animated visual effect with ~35% lower CPU usage and resolves
most or all of the terminal rendering issues associated with the
overlay.
This rule is generally trying to be helpful, but it doesn't like a few
places in our code base where we're intentionally listing out all of the
well-known cases. Given that, just disable it.
https://realm.github.io/SwiftLint/no_fallthrough_only.html
In order to support running from both the repository root and from
within Xcode project, and to keep things generally organized, our
primary .swiftlint.yml configuration file lives under macos/.
This change introduces a root-level .swiftlint.yml which limits the file
scope to macos/ and then includes macos/.swiftlint.yml for the rest of
the directives.
This unlocks a few benefits:
- We no longer need to pass an explicit `macos` path argument in any of
our invocations. SwiftLint will do the right thing when run either from
the repository root or from within the macos/ directory.
- It lets us easily exclude the macos/build/ directory (and re-enable
the 'deployment_target' rule). In the previous setup, this was more
challenging than you'd expect due to SwiftLint's path resolution rules
and required passing even more arguments like `--working-directory`.
The only downside is adding a new file to the repository root, but that
feels like the right trade-off given the benefits and conveniences.
In order to support running from both the repository root and from
within Xcode project, and to keep things generally organized, our
primary .swiftlint.yml configuration file lives under macos/.
This change introduces a root-level .swiftlint.yml which limits the file
scope to macos/ and then includes macos/.swiftlint.yml for the rest of
the directives.
This unlocks a few benefits:
- We no longer need to pass an explicit `macos` path argument in any of
our invocations. SwiftLint will do the right thing when run either
from the repository root or from within the macos/ directory.
- It lets us easily exclude the macos/build/ directory (and re-enable
the 'deployment_target' rule). In the previous setup, this was more
challenging than you'd expect due to SwiftLint's path resolution rules
and required passing even more arguments like `--working-directory`.
The only downside is adding a new file to the repository root, but that
feels like the right trade-off given the benefits and conveniences.
Rendering the Secure Keyboard Input overlay using
innerShadow() can strain the resources of the main
thread, leading to elevated CPU load and in some
cases extended disruptions to the main thread's
DispatchQueue that result in lag or frozen frames.
This change achieves the same animated visual
effect with ~35% lower CPU usage and resolves most
or all of the terminal rendering issues associated
with the overlay.
SwiftLint <https://realm.github.io/SwiftLint/> is both a linter and
formatting. It's a popular way to spot issues and enforce a consistent
style.
Our SwiftLint configuration lives in macos/.swiftlint.yml, where is is
automatically discovered. It's very configurable, and I made an initial
pass as some basic, weakly-opinionated rules. The "TODO" section lists
rules that currently have violations but can be easily (auto)fixed in
follow-up commits.
Our integration is CLI-based. Similar to our other support tools, we
expect developers to install `swiftlint` via nix or e.g. Homebrew.
This is documented in HACKING.md.
We also have an optional Xcode integration, for in-editor feedback. When
`swiftlint` is available, it's run as a script-based Build Phase.
SwiftLint supports an auto-fix mode (--fix). Agents are aware of this
via AGENTS.md.
The rules are enforced using a (nix-based) CI job.
Switch to using the existing UTType.unixExecutable constant for this
operator, which also lets us remove a failure path. Also, use the
completion-based setDefaultApplication() variant to handle errors.
This simplifies the code enough that we don't need the additional
NSWorkspace+Ghostty extension functions.
This PR enables iTerm2-like one button "Set Ghostty as Default Terminal
App" functionality on macOS, making it easier to open a directory in
Ghostty, run shell scripts when mouse clicking, etc.
We already had an established Ghostty.Shell namespace (previously a
struct; now a more idiomatic enum), and locating these functions next to
each other makes it clearer how they relate to one another.
We already had an established Ghostty.Shell namespace (previously a
struct; now a more idiomatic enum), and locating these functions next to
each other makes it clearer how they relate to one another.
Xcode wants these to be sorted and will update this list when the
project file is saved so proactively make this change before it gets
mixed up in other work.
## Summary
- Fixes#10345 — `copy_title_to_clipboard` now copies the user-set
custom title instead of the raw terminal title
- Adds a new `copy_title` apprt action as [suggested by
@mitchellh](https://github.com/ghostty-org/ghostty/issues/10345#issuecomment-2601002974)
- Each platform (GTK + macOS) resolves the effective title (user
override → terminal title fallback) before copying to clipboard
## Changes
- **`src/apprt/action.zig`** — New `copy_title` void action
- **`include/ghostty.h`** — C ABI enum entry
- **`src/Surface.zig`** — Binding handler now dispatches apprt action
instead of inline logic
- **`src/apprt/gtk/class/surface.zig`** — `getEffectiveTitle()` helper
(returns `title_override orelse title`)
- **`src/apprt/gtk/class/application.zig`** — GTK action handler
- **`macos/.../Ghostty.App.swift`** — macOS handler using
`surfaceView.title` + `NSPasteboard`
*Note*: This PR was *AI* assisted.
When a user renames a surface via "Change Terminal Title" and then
uses copy_title_to_clipboard, the raw terminal title was copied
instead of the custom name.
This adds a new `copy_title` apprt action so each platform resolves
the effective title (user override or terminal-set) before copying
to clipboard.
Fixes#10345
When we're building an input string that's explicitly meant to be used
as a shell command, quote it using the same logic as Python's
`shlex.quote` function.
This specifically addresses issues we've seen when open(1)'ing Ghostty
with filename arguments that contain spaces.
See #2633, #3030
When we're building an input string that's explicitly meant to be used
as a shell command, quote (escape) it using the same logic as Python's
shlex.quote function.
This specifically addresses issues we've seen when open(1)'ing Ghostty
with filename arguments that contain spaces.
[Reference](https://github.com/insidegui/AudioCap). This is Apple's latest system for allowing apps to access loopback audio streams eg: Desktop-Audio, Window-Audio, etc...
Refer to discussion #10000
When a tab contains only a single split, resize_split and
toggle_split_zoom actions now return false (not performed). This allows
keybindings marked with `performable: true` to pass the event through to
the terminal program.
The performable flag causes unperformed actions to be treated as if the
binding didn't exist, so the key event is sent to the terminal instead
of being consumed.
- Add isSplit() helper to SplitTree to detect single-pane vs split state
- Update GTK resizeSplit/toggleSplitZoom to return false when single
pane
- Update macOS resizeSplit/toggleSplitZoom to return Bool and check
isSplit
- Add unit test for isSplit method
### Background
~~I was trying to add a few UI test cases for
`macOS-titlebar-style`[Already in this PR]~~. In order to do this, I
need a way from `GhosttyKit` to load a temporary configuration without
messing around with users'.
### Changes
- Add `ghostty_config_load_file` using the existing
[`loadFile`](dafb9e89a3/src/config/Config.zig (L3399))
- Use `xcbeautify` to format test&build errors
**Couldn't find a way to do this in `GhosttyXcodebuild`, if you have a
better approach please let me know!**
- Add GhosttyUITests target and test cases for
`GhosttyTitlebarTabsUITests`(#2349) and `GhosttyThemeTests`(#9360)
### NOTE
Running UI tests on the runner could be **very** slow and I couldn't
find a way to guarantee success, so I made these only runnable by
manually testing in Xcode.
Better to squash this🤪
> > Some of the test cases could fail when testing all the cases
together; a rerun would succeed.
referring to the discussion:
https://github.com/ghostty-org/ghostty/discussions/9814
This is a very small change addressing the behavior for closing the
search bar. This removes an extra step when closing the search bar if
the query is empty
When a tab contains only a single split, resize_split and toggle_split_zoom
actions now return false (not performed). This allows keybindings marked with
`performable: true` to pass the event through to the terminal program.
The performable flag causes unperformed actions to be treated as if the
binding didn't exist, so the key event is sent to the terminal instead of
being consumed.
- Add isSplit() helper to SplitTree to detect single-pane vs split state
- Update GTK resizeSplit/toggleSplitZoom to return false when single pane
- Update macOS resizeSplit/toggleSplitZoom to return Bool and check isSplit
- Add unit test for isSplit method
Clicking on the icon immediately advances to the next one. Hovering on
the icon pauses the automatic cycling, and the "help" tooltip displays
the icon's configuration name (for `macos-icon`).
Adds the `selection_for_search` action, with Cmd+E keybind by default.
This action inputs the currently selected text into the search
field without changing focus, matching standard macOS behavior.
After rearranging panes, the window becomes permanently unmovable.
Grab handles temporarily set `window.isMovable = false` on hover to prevent
window dragging from interfering with pane dragging.
Override `viewWillMove(toWindow:)` to catch when the view is being removed from
the window. This lifecycle method is called before the window reference
becomes nil, allowing us to restore `window.isMovable`.
- Fixes#9991
> Modifying the subview of NSThemeFrame seems "dangerous" and
unpredictable.
- Provides correct `intrinsicContentSize` as previous
`NSHostingView<TerminalView>` did
> Fixes regression caused by #10046
> [!NOTE]
> AI Proofread some of my comments
This is a regression introduced when we added macOS support for custom
entries. I mistakingly thought that only custom entries were in the
config, but we do initialize it with all!
Fixes#7643
This commit address the issue with 3 minor fixes:
1. Initialize ghostty lib before app start, or global allocator will
be null.
2. `addSublayer` should be called on CALayer object, which is the
property 'layer' of UIView
3. According to apple's [document](https://developer.apple.com/documentation/metal/mtlstoragemode/managed?language=objc),
managed storage mode is not supported by iOS. So always use shared
mode.
FYI, another [fix](https://github.com/mitchellh/libxev/pull/204) in libxev
is also required to make iOS app work.
> **Note**: This is a re-submission of #9952, which was closed in favor
of #9975. However, as noted in my [comment on
#9975](https://github.com/ghostty-org/ghostty/pull/9975#issuecomment-3677916608),
the issue still persists.
## Summary
- Fix `window-position-x/y` not being applied when `window-width/height`
is also configured
## Problem
When both `window-position-x/y` and `window-width/height` are
configured, the window position was not being applied correctly. The
window would appear near the center of the screen instead of the
specified position.
This worked correctly in v1.2.3 but regressed afterwards.
## Root Cause
This is a regression introduced in c75bade89 (#9747).
The commit refactored the default size logic from a computed `NSRect?`
property to a `DefaultSize` enum with `.frame` and
`.contentIntrinsicSize` cases.
**Before (working):**
```swift
private var defaultSize: NSRect? {
// ... calculate frame ...
return adjustForWindowPosition(frame: frame, on: screen) // ← position was applied
}
```
**After (broken):**
```swift
enum DefaultSize {
case frame(NSRect)
case contentIntrinsicSize
func apply(to window: NSWindow) {
case .contentIntrinsicSize:
window.setContentSize(size)
window.constrainToScreen()
// ← adjustForWindowPosition call was lost
}
}
```
When `window-width/height` is configured, the `.contentIntrinsicSize`
case is used. This case only called `setContentSize` and
`constrainToScreen`, but did not apply the window position adjustment.
## Why This Fix is Correct
`DefaultSize.apply()` is intentionally **not** responsible for
position—it only handles **size**:
1. `apply()` is also called from `returnToDefaultSize(_:)` menu action
2. When user triggers "Return to Default Size", only the **size** should
reset—**not the position**
3. If we added position logic inside `apply()`, the window would
unexpectedly jump back to its initial position
Therefore, position adjustment belongs **outside** of `apply()`,
specifically during initial window setup in `windowDidLoad`.
## Fix
Call `adjustForWindowPosition` after applying the content intrinsic size
to ensure the window position is correctly set during initial window
creation.
When window-width/height is configured, the window size is set via
setContentSize in windowDidLoad. However, window-position-x/y was not
being applied after this resize, causing the window to appear at an
incorrect position.
This was a regression introduced in c75bade89 which refactored the
default size logic from a computed NSRect property to a DefaultSize
enum. The original code called adjustForWindowPosition after calculating
the frame, but this was lost during the refactoring.
Fixes the issue by calling adjustForWindowPosition after applying
contentIntrinsicSize to ensure window position is correctly set.
Part of #9963
This adds a new special key `catch_all` that can be used in keybinding
definitions to match any key that is not explicitly bound. For example:
`keybind = catch_all=new_window` (chaos!).
`catch_all` can be used in combination with modifiers, so if you want to
catch any non-bound key with Ctrl held down, you can do:
`keybind = ctrl+catch_all=new_window`.
`catch_all` can also be used with trigger sequences, so you can do:
`keybind = ctrl+a>catch_all=new_window` to catch any key pressed after
`ctrl+a` that is not explicitly bound and make a new window!
And if you want to remove the catch all binding, it is like any other:
`keybind = catch_all=unbind`.
Fixes#9952Fixes#9969
This fixes our `constrainToScreen` implementation to properly clamp the
window size to the visible screen its coming on as documented. Further,
this addresses the positioning problem, too.
This hides the macOS tab overview when the `escape` key is pressed.
Our solution is a bit blunt here and I don't think its right. I think we
have a first responder problem somewhere but I haven't been able to find
it and find the proper place to implement `cancel` (or equivalent) to
hide the overview. I tried implementing `cancel` in all the places I
expect the responder chain to go through but none worked.
For now let's do this since it is pretty tightly scoped!
Mitchell Hashimoto