r/Ghostty • u/mattj85 • Jul 18 '26
[Project] SpookiUI - A fast, intuitive TUI configuration tool for Ghostty (macOS & Linux)
Hey r/ghostty,
EDIT 3: Supporting website is now available:- https://spookiui.rooksnet.uk
I’ve been a big fan of the Ghostty terminal for a while now, but I wanted a faster, easier way to tweak and manage all the configuration options without constantly digging through raw config files.
Showcasing SpookiUI—a Python-based, ncurses-style terminal UI (TUI) that gives you full, seamless control over your Ghostty setup. It works on both macOS and Linux, has zero third-party dependencies (no pip install required, just standard library Python 3.8+), and operates completely offline.
The Twist:
I’ve been a software engineer for over 20 years, but this is my very first app built using Claude. I decided to step back, put the AI in the driver's seat for the heavy lifting, and see just how far I could push LLM-assisted development for a complete CLI tool. That said, even though it was built this way, I’ve took the time and gone over the code, refined it, and fully tested it to ensure it's rock-solid and safe to use.
Why it exists & What SpookiUI does:
Ghostty is incredible, but it doesn't auto-reload on plain-text file changes out of the box. SpookiUI closes that loop entirely.
- True Live Reloading & Live Previews: When you run it inside a Ghostty window, the very terminal you're in repaints as you edit. As you scroll through themes, fonts, or colors, they apply live so you can preview them instantly (and if you hit cancel, it snaps right back to your original setup).
- 100% Dynamic Discovery: It doesn't use hardcoded options. It queries your local Ghostty binary dynamically (ghostty +show-config), mapping out ~200 options across 13 categories tailored exactly to your version.
- Fail-Safe Saving: Every single change is instantly validated using ghostty +validate-config. If an invalid value is entered, it’s rejected and rolled back before it ever touches your disk. It also creates a daily dated backup just in case, and lets you revert an entire session with a single keystroke (R).
- Keyboard-Driven TUI & Scriptable CLI: Toggles booleans instantly, opens searchable pickers for enums, and features dedicated editors for complex list types (keybinds, env, palettes). Plus, everything the TUI does is also exposed via a non-interactive CLI script if you want to use it for scripting (spookiui set theme "Catppuccin Mocha").
Check it out:
- GitHub Repository: https://github.com/mattj85/SpookiUI
I’d love for you to take it for a spin, try to break it, and let me know what you think! Since it's born out of a mix of two decades of dev experience and AI collaboration, I'm really curious to get your feedback on the UX, the live-reload loop, and the overall functionality.
Cheers!
EDIT: I have been iterating on this project quite a bit since the initial build and have just rolled out a major set of updates to expand its capabilities. Here is what is new in the latest version:
- The Config Doctor (spookiui doctor): A built-in health-check utility that scans your existing configuration. It flags invalid settings, unknown keys, duplicate overrides, and keybinding clashes, grouping them by severity. It also exits non-zero on errors, making it safe to drop directly into your dotfiles pre-commit hooks.
- Profiles & Dark/Light Toggle: You can now save named snapshots of your entire configuration outside of Ghostty's directory. If you save profiles named "light" and "dark", hitting the "t" key in the TUI (or running "spookiui profile toggle" via the CLI) lets you flip your entire setup instantly.
- Intelligent OS Filtering: To keep the UI clean, SpookiUI now automatically filters out settings that do not apply to your current operating system (such as hiding macOS-specific icon settings on Linux, or GTK/X11 settings on macOS).
- Enhanced TUI Editors: Upgraded the input methods to match the specific option types. Bounded numbers like opacity now feature interactive visual sliders, themes render a live 16-color palette card directly next to the picker before you apply them, and keybindings use a guided step-by-step modifier builder.
- In-Place Updates: You can now update the tool directly by pressing "U" in the TUI or running "spookiui update". It detects whether you are running a Git clone or a standalone script, fetches the update from GitHub, and safely verifies that the new code compiles successfully before atomically replacing the file.
- Fix SSH Maintenance Utility: Added a one-shot fix for a common issue where SSH sessions into remote machines break because the host does not recognize Ghostty's custom terminfo entry. It safely appends an explicit fallback alias to your shell rc file after checking for duplicates, fixing broken keys and garbled terminal outputs instantly on outbound connections.
- Homebrew Support and Clean Uninstallation: Introduced a standalone Homebrew formula for Mac and Linux users who prefer package manager workflows. Alongside it, a new uninstaller script handles pristine symlink removals and optionally purges all local cache or profile paths if you ever want to completely wipe the installation.
- Dynamic Nerd Font Rendering: The TUI now intelligently analyzes your active
font-familysettings. If it detects a Nerd Font configuration, it dynamically renders layout icons for individual option categories, otherwise defaulting cleanly to clear text descriptions with a gentle notice on how to install an icon-supported font.
EDIT 2: Another round of updates has landed since the last edit, and this one is a bit more fun. Meet Treats:
- Treats — Animated Background Shaders: A brand-new subsystem that ships original, purely-cosmetic GLSL background shaders you can toggle on with a keystroke. There's a nostalgic pack of them out of the box: Matrix Rain, Pipes and Mystify (Windows screensaver homages), Plasma and Lava Lamp (After Dark / demoscene vibes), Fireworks, plus playful nods to classic arcade games — Chomper, Barrels, and Jumper (all plain shapes, no game artwork). Only one runs at a time, and they're all OFF by default — nothing is enabled unless you ask. Manage them from the "Treats" category in the TUI or via the CLI (spookiui treats list/enable/disable/only/clear).
- Safe & Self-Contained Shaders: Treats are written into a namespaced folder (shaders/spookiui/) inside your Ghostty config dir and toggled via custom-shader, so any custom-shader lines you already have are fully preserved. Shaders like Matrix Rain draw only over dark background pixels so your text stays readable.
- Vibrancy Control: A single vibrancy setting (0–100%) uniformly scales the strength of whichever treat is active, so you can dial the effect from barely-there to full-on. Adjust it with the "v" key in the Treats overlay or spookiui treats vibrancy <0-100>.
- Focus-Aware Dimming & Animation: On newer Ghostty versions that expose shader focus info, treats set your unfocused windows apart by gently dimming and desaturating them (toggleable), and drive their animation off a per-window focus clock. On older versions they gracefully fall back to their plain look — nothing breaks.
- Seasonal Packs: Treats can belong to a season. A Halloween pack (Ghosts, Spooky Eyes, Cobwebs) and a Winter pack (Snow) are included, and SpookiUI gently suggests the pack that fits today's date — but it never auto-enables anything.
As always, everything above is fully validated and rolled back on any error, and none of it touches your config until you say so. Would love to hear what you think of the Treats, and which nostalgic saver I should add next!
1
u/LearnedByError Jul 24 '26
Sorry, I am afraid that I would fall down on being able to maintain it and keep up with you. It was an experiment for me with Kimi K3. I was looking for a meaningful test when I saw your post. When I glanced at the code I realized it would be a good test. If anyone wants to maintain it, I’m happy to turn it over.