GUI preference pane

[haze]

I'd like to contribute a native preference pane for Ghostty. I'm only comfortable with working on the macOS variant of this feature, so I'll only be commenting on preference panes native to macOS, but I want to make it clear that this issue can also be used for discussion around other windowing systems and their respective UX/UI guidelines.

macOS

macOS has moved away from the older preference pane style to a newer, iOS-esque style sidebar navigation view. Personally, I'm indifferent, but I find discovery to be calmer in the previous iteration.

Pre macOS Ventura	Post macOS Ventura

I'd also like to drop some inspiration from some other cool Mac apps:

Nova

Main preference pane	Child view

CodeEdit

Terminal.app

My questions are:

• Which preference pane style should Ghostty adopt?
• Are there any configuration elements that require a richer set of inputs than the standard methods defined in SwiftUI?
• Would it make sense to stay native to each platform, or have a window that shares its layout across all desktop environments?

[mitchellh]

This would be very helpful! I'm sure you'll run into some limitations of the Ghostty C API, but I'm happy to help with those as you run into them. Your questions:

Which preference pane style should Ghostty adopt?

I like Nova's.

Are there any configuration elements that require a richer set of inputs than the standard methods defined in SwiftUI?

Probably, but you can just focus on the easy ones to start. When we get there we'll figure it out.

Would it make sense to stay native to each platform, or would it make sense to have a window that shares its layout across all desktop environments?

Nah, let's make it native per platform. These things tend to have very different idiomatic feel per platform.

[kjvdven]

It takes more clicks for the Nova's design to switch to another section.

[goonzoid]

Thanks for pulling together some examples from a few different apps / styles. It'll be helpful for discussion.

I want to take a small step back and ask a different question: should Ghostty even have a preference pane? For me, text based configuration is a huge selling point for an application. Before Ghostty I was an iTerm2, Alacritty, and (briefly) Kitty user, and I much preferred the experience of configuring Alacritty and Kitty in text, compared to iTerm2 in the GUI. I don't think it makes sense for every app domain, but terminals are inherently text based, so it feels like a good fit to me.

Of course I can see the other side of this argument. For configuring colours and themes in particular, there's no doubt that a well designed GUI can provide a richer experience.

Maybe we can have the best of both - a preference pane as an interface for editing a plain text file?

One other thought more directly related to your initial question: I think @mitchellh had mentioned the idea of web based configuration at some point. Obviously the cool thing about this is that it can easily be completely cross platform. EDIT: Mitchell clearly types faster than me. Seems like the native per platform approach is favored (and I don't disagree).

[mitchellh]

I think a graphical preference window is desirable. Its something I'd like to see. But that doesn't mean doing away with the text-based config, either!

Maybe we can have the best of both - a preference pane as an interface for editing a plain text file?

I think this is worthwhile and in line with what I was thinking.

The way we do parsing of the text file right now it'd be a pain to preserve whitespace and comments in order to rewrite it. I think we should instead go with a priority approach, something like: GUI takes priority over the XDG file at ~/.config/ghostty/config. This way, we never overwrite a user's text config.

We store the GUI config in NSUserDefaults (or something). The reason I want to use NSUserDefaults is for iCloud syncing. I think it'd be a really nice value-add for GUI-based configuration for macOS to automatically sync between all devices, in a way that the user owns all their data (i.e. we don't have to run any service -- which is always going to be a hard no for us).

The exact value stored in NSUserDefaults can be an "encoded" ghostty_config_t (we need to add an API for this), but since its owned by the GUI, we don't need to worry about preserving whitespace or comments. We'd only write values that differ from defaults.

This is where we'd load it: https://github.com/mitchellh/ghostty/blob/e11d737a80f570488a87d0b9a635b318904b9252/macos/Sources/Ghostty/AppState.swift#L130-L132

[haze]

Thanks for pulling together some examples from a few different apps / styles. It'll be helpful for discussion.

I want to take a small step back and ask a different question: should Ghostty even have a preference pane? For me, text based configuration is a huge selling point for an application. Before Ghostty I was an iTerm2, Alacritty, and (briefly) Kitty user, and I much preferred the experience of configuring Alacritty and Kitty in text, compared to iTerm2 in the GUI. I don't think it makes sense for every app domain, but terminals are inherently text based, so it feels like a good fit to me.

In my mind, the preference pane would be an alternative editor for the text based configuration file; it would load it's configuration from the same text file you can edit on disk and save changes to that file as well. This unfortunately means that after using the preference editor, defaults are exposed explicitly.

I think a GUI preference pane not only helps with configuration discovery (beyond parsing the config struct as noted in the READMEs) but also ease of use. It's probably much nicer to see the color you're editing in real time without relying on shell/editor functionality to preview the hex.

Fig also has a cool preference pane where they have a video demonstrating the outcome of your settings, which makes understanding what you selected easier. I like that feature a lot.

[goonzoid]

I think it'd be a really nice value-add for GUI-based configuration for macOS to automatically sync between all devices.

For sure, that's a killer feature (when iCloud syncing works as it's supposed to 😬).

GUI takes priority over the XDG file at ~/.config/ghostty/config.

Agree in principle, but slightly scared that this could end up feeling a bit opaque or hard to manage, and lead to very frustrating "why isn't my config being applied?" type moments. Not advocating against it, but just calling out something I think it's worth being thoughtful about if we have multiple config sources. Your comment about only writing values that differ from defaults goes some way towards solving this, but I think we might also want to do something to make it very visible to user which values are being stored in user defaults.

[mitchellh]

Merging in #1032 here. I know this is about a GUI pref pane but I think including this suggestion as a first step or even alternate option for some people makes sense.

Currently the Settings menu item on MacOS is greyed out and the shortcut cmd+, does nothing.

We could implement the open settings menu item and shortcut to open the settings file with the default system editor.

An example on which to base the implementation could be Kitty, which already has this feature.

[erf]

I find the CodeEdit design quite nice - and maybe we should adhere to the new macOS design style, like using the sidebar, to be more future proof?

I'm not sure if the design guideline forces this type of design but there is some more information in the video at Adopt the new look of macOS and at Settings.

I find the text based XDG config file nice. I have it in a "dotfile" type git repo and it's easy to change and push changes. I like the idea of a native GUI based settings view as well, but i rather it don't interfere or override my text configuration if possible. Maybe the GUI window could read the XDG config on open and save to it again, preferably, without messing up the file too much, and that iCloud sync could be OPT-in ? Maybe this would be difficult with the current file and another file format would be more suitable. VSCode uses a JSON file which might be more suitable and cross-platform. Although, less human-readable it might be a good balance for both machines and humans (although i do like the TOML format). The settings would have to be converted between native macOS format (NSUserDefaults?) and our text format in order to be synched.

[clebs]

I would be up to try to build the file opening option which can be expanded upon as the proposal evolves.

I do not have experience with swift, but as mentioned in my duplicate issue, Kitty does it that way and would serve as reference implementation.

[clebs]

I have been delving into the code and think I have a grasp on how to add actions to the different runtimes and bring them together in the platform independent core (+ Bindings).

@mitchellh would it be fine to give this a try on Mac OS first and subsequently on Linux and Windows?

I also was thinking if it would be worth it to add an editor config field that would allow to tell Ghostty which editor to use in actions that require it (similar to how it can be set on git). Default would always be OS default editor.

[mitchellh]

Yes, feel free to take a stab at it! I'm open to this functionality.

EDIT: And yes, it's okay if it only supports one platform to start. Don't worry about Windows, yet.

[clebs]

Just added the first step for the preferences feature on MacOS here #1116. This enables the settings menu item and binds the given shortcut to it (cmd + ,). It is implemented as action, so it can be used in the config file with another binding if desired as open_config.

In the future this action can be recycled as a button on the preferences panel being discussed here.

I will next add the linux shortcut and menu in the same way next.

[gwww]

Reading through the comments here, it seems there is interest in keeping both config file and GUI. I'm assuming only one of the two configs would be used at any one time. Is it something such as if a config file exists, use that. If no config file exists assume its the GUI?

Like some others on this thread, I'm partial to config file that is a part of my dotfiles repo.

[rnpatel]

I would hope that it's not either-or, but rather a preference pane that reads and writes the configuration file.

[JoshBashed]

I'm working on this now. These are my thoughts

[kjvdven]

In the examples, for new mac os and code edit, the search is in the left side bar, probably so that it won't scrolls along.
Is the top of the right panel fixed? I assume it is.

[JoshBashed]

@kjvdven It is part of the "toolbar"

[mitchellh]

See this too: #2354 (comment)

[mitchellh]

I want to note that to ease long term maintenance, we have an opportunity to potentially programmatically generate the UI, especially with SwiftUI. We already generate a Zig package help_strings that we use to automatically generate our man pages, markdown, HTML, etc.

I don't think that has enough information today but we can expand on that to provide types, options (enums), etc. And from there we can probably expose it via the C API (libghostty) that macOS uses. Using this we can probably use Zig to generate enough rich information as needed by libghostty consumers to generate a settings view.

[lucanos]

I'd suggest having a look at Tabby.

It has a GUI for setting preferences, but the preferences are read from/written to a JSON config file. So you can manually change the JSON file, or you can make changes via the GUI.

Having the config file also means you can sync the file between machines (even across OSes) so you have the same settings/accounts/stored credentials everywhere.

[ManiProjs]

Hello! I really love this project and i like to contribute for some bugfixes and features (such as adding support for Windows and GUI settings pane)

In my opinion, it would be nice to add a UI for Ghostty settings. Because if someone doesn't know how to change a config, he/she doesn't need to search for "how to change settings for ...... in Ghostty"

[rhodes-b]

Windows is still a bit out, it requires getting libghostty stable first
https://github.com/ghostty-org/ghostty/?tab=readme-ov-file#roadmap-and-status
look at the roadmap

There has been work by a few separate people for windows though look in the discord if youre interested about that

[ManiProjs]

@rhodes-b Aha... Ok. I can't get those signs. I don't know what do they mean. (Windows was off-topic because here, we're talking about a UI for settings)

[rhodes-b]

Im not saying windows is off topic, its just that there isnt any windows support right now so it doesnt make too much sense to jump straight into adding a interface for something that doesnt exist

#2563
for adding windows support

[ManiProjs]

Ok, no problem. I meant that the Windows support that I said in **my** comment was off-topic, not yours.

…

On Fri, Jan 31, 2025 at 17:59 Brice ***@***.***> wrote: Im not saying windows is off topic, its just that there isnt *any* windows support right now so it doesnt make too much sense to jump straight into adding a interface for something that doesnt exist #2563 <#2563> for adding windows support — Reply to this email directly, view it on GitHub <#2354 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BMLYYWT5WYRCBK4IAW4VAPT2NOCGFAVCNFSM6AAAAABQIRADN6VHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTEMBRHA2DGMQ> . You are receiving this because you commented.Message ID: ***@***.***>

[mitchellh]

I noted this in an earlier comment but I after thinking through the various use cases today, I want to reaffirm a few design points:

The GUI should not modify any user text configuration files. The GUI should be encoding and storing its configuration in whatever form it wants to (NSUserDefaults for macOS, gsettings for GTK, etc. just examples, not required). This will make integrating with platform-native functionality (i.e. cloud syncing on macOS) easier. Further, I think modifying a user's text file opens up a can of worms around formatting, comment-preservation, etc.

The GUI settings should take priority over text config files. The primary reason is because if I set something in a GUI element, I would expect it to ALWAYS be that set setting. It would be extremely unintuitive if a user set say... a padding value, and the padding value didn't take effect because a text file overrode it (even if the GUI noted this). Further, this always enables using the GUI to experiment with configs before you may want to persist them in a text file.

The GUI should have a "reset" button not a "defaults" button. Reset would unset all values from the GUI to the values that would be used by the text file (if it exists). If no text file exists, this is the same as defaulting.

Overall, the hardest UX is the UX where a user has mixed config file and GUI settings. I think that overall this will likely be relatively rare, since I think users lean one way or the other. However, we will need to be mindful of surfacing information such as the source of a config value (default, text, or gui) and seeing if that helps things.

I think for an initial version, we should optimize for the user who is purely GUI or purely text, and just try to not shoot ourselves in the foot over the mixed case. The designs above help move us towards this since you'd never be stomping on text contents (and a reset would bring you back to pure text).

[00-kat]

#5623 and #5681 (GTK side) are relevant.

[bo2themax]

It seems like there aren't any visible working-in-progress PRs or branches that implement this feature, and I really want this🙈

if someone is already working on this, please let me know to avoid duplicate works, and I'd love to contribute to your current work as well

Here are my thoughts based on the latest design points given by @mitchellh:

• Based on current Ghostty.Config, abstract a protocol for both text-based config and GUI-based config (macOS platform-specific), e.g. GhosttyConfiguration
• Search and summarise current places that use Ghostty.Config and modify ghostty_config_t for future testing
• Add a new Configuration that conforms to GhosttyConfiguration to serve as the source of truth for the new settings panel

  This is where one should implement design points 1 and 3

• Choose the correct configuration in Ghostty.App which implements design points 2 (e.g. if GUI settings are not modified/created by the user, then text settings will be used)
• Test the idea using hard-coded GUI settings (better with unit testing)
• Draw those views🎨

These are my initial high-level thoughts after a quick skim through of the current code base about how configuration works. Might encounter more technical challenges along the way.

[bo2themax]

This is a valid point too. I'm thinking of using a Swift macro to do that, but haven't thought it through yet.

[bo2themax]

While testing my ideas, I found embedding a theme preview surface in the settings window quite difficult. I managed to embed a full surface and set an initial command ghostty +list-themes —preview=“0x96f” to preview a specific theme. However, this is too heavy for a settings window. I’m wondering if there’s a better way to simply embed list_themes.Preview.

Currently, I understand that Preview generates placeholder text by code. I tried to modify it but haven’t succeeded. So... I’m asking if anyone knows a better approach.

Claude Code seems to over-engineer it every time resulting in massive changes😢.

Another thought I might just echo a bunch of predefined lines.

[bo2themax]

It seems like there aren't any visible working-in-progress PRs or branches that implement this feature, and I really want this🙈

if someone is already working on this, please let me know to avoid duplicate works, and I'd love to contribute to your current work as well

Here are my thoughts based on the latest design points given by @mitchellh:

• Based on current Ghostty.Config, abstract a protocol for both text-based config and GUI-based config (macOS platform-specific), e.g. GhosttyConfiguration
• Search and summarise current places that use Ghostty.Config and modify ghostty_config_t for future testing
• Add a new Configuration that conforms to GhosttyConfiguration to serve as the source of truth for the new settings panel

  This is where one should implement design points 1 and 3

• Choose the correct configuration in Ghostty.App which implements design points 2 (e.g. if GUI settings are not modified/created by the user, then text settings will be used)
• Test the idea using hard-coded GUI settings (better with unit testing)
• Draw those views🎨

These are my initial high-level thoughts after a quick skim through of the current code base about how configuration works. Might encounter more technical challenges along the way.

WIP branch: https://github.com/bo2themax/ghostty/tree/feature/settings-ui-macos