seth-linux-theme/SESSION.md

SESSION.md — Seth Linux Theme

Project Summary

Centralized Linux desktop theme for Seth's GNOME setup. Black titlebars, square corners, ultra-thin headerbars, dark mode with orange accent (#D35400). Configs for GTK3/4 CSS, kitty terminal, and GNOME gsettings.

Gitea

• Repo: https://git.sethpc.xyz/Seth/seth-linux-theme

Context Files

• gtk-3.0/gtk.css — GTK3/4 headerbar CSS (same file used for both)
• kitty/kitty-theme.conf — kitty terminal overrides (borderless, black titlebar, tab bar config, keybindings)
• kitty/tab_bar.py — custom tab bar: flat tabs + right-aligned status (git, cpu, mem, uptime, host, clock)
• kitty/tab-bar-hide.conf / tab-bar-show.conf — toggle snippets (may be unused now with inline --override approach)
• gnome/apply-gnome-settings.sh — GNOME dark mode, orange accent, Super+right resize
• install.sh — deploys all configs to target user's ~/.config

Session Notes

Architecture

• GTK CSS goes in ~/.config/gtk-3.0/gtk.css and ~/.config/gtk-4.0/gtk.css (same content)
• kitty uses its own config, not GTK — wayland_titlebar_color only works with CSD, not Mutter SSD
• hide_window_decorations yes removes Mutter's server-side decorations from kitty entirely (borderless)
• GNOME Shell rounded corners are Mutter-controlled, not GTK CSS — need GNOME Shell theme or extension to override DE-wide
• resize-with-right-button true enables Super+right-drag to resize (was disabled by default)

Deployment

• Desktop runs on steel141 (192.168.0.141) under seth@ user
• claude@ is headless, no DE — GUI configs must target /home/seth/.config/
• From claude@: sudo -u seth cp <file> /home/seth/.config/...
• GTK3 apps pick up CSS changes live (open new window). GTK4/libadwaita apps need full relaunch. Kitty needs relaunch.

Current state (2026-04-07)

• GTK CSS: black headerbar, square corners, white text, transparent buttons, #999 backdrop text/icons, 36px min-height
• Kitty: borderless (hide_window_decorations yes), JetBrainsMono Nerd Font, custom tab bar with status area
• Kitty tab bar: flat style (no powerline), user@ prefix for non-seth users, right-aligned status (git branch, CPU%, memory, uptime, hostname, clock) with Nerd Font icons in orange
• Kitty tab bar toggle: F12 hides (min_tabs=999), Shift+F12 shows (min_tabs=1) via remote_control load-config --override
• GNOME: dark mode, orange accent, Super+right resize enabled

Open issues

• GNOME Shell rounded window corners — Mutter hardcodes CSD corner rounding at compositor level. No CSS override possible (tried border-radius: 0 !important on all nodes). No gsetting exists. GNOME Shell CSS .window-frame doesn't control it either. Only fix: patched Mutter or a GNOME Shell extension that modifies Mutter's clipping behavior. "Rounded Window Corners Reborn" extension only ADDS rounding (shader overlay), doesn't remove native rounding.

Resolved issues (2026-04-07)

• Nautilus sidebar/main headerbar height mismatch — Fixed by targeting headerbar stackpage > box and headerbar stack with min-height: 0 and zero padding. Root cause: NautilusPathBar inside a GtkStack in the main headerbar was taller than the sidebar's simple AdwWindowTitle.
• Thin gray border line at top of headerbar — Fixed by targeting decoration, window.csd, .titlebar:not(headerbar), and toolbarview > .top-bar with border: none; box-shadow: none; outline: none. Was a CSD decoration border, not on the headerbar node itself.
• User Themes extension — Installed (gnome-shell-extension-user-theme apt package), enabled, Sethian theme set via gsettings set org.gnome.shell.extensions.user-theme name "Sethian". Required gnome-shell --replace to detect newly installed extension.

Design decisions

• 2026-04-07: Use stock Adwaita dark + CSS overrides, not a full third-party theme — minimal maintenance, survives GNOME updates
• 2026-04-07: Kitty borderless rather than trying to style Mutter's SSD — cleaner, no titlebar to fight with
• 2026-04-07: adw-gtk3 not needed if only overriding headerbar — stock Adwaita + user CSS is sufficient
• 2026-04-07: Flat tab style over powerline — powerline creates clipping artifacts with long titles, flat is simpler
• 2026-04-07: JetBrainsMono Nerd Font — needed for icon glyphs in tab bar status area
• 2026-04-07: Tab bar toggle via remote_control load-config --override — no scripts/sockets needed, inline kitty RC

DANGER — never do these

• NEVER run gnome-shell --replace from claude@ session — it replaces seth's shell process, kills the active session, resets all extensions and theming to defaults. Use dbus-send reexec or ask seth to relog instead.

Kitty architecture notes

• Repo files (seth-linux-theme/kitty/) and Seth's live config (/home/seth/.config/kitty/) are separate copies, not symlinks — must deploy manually
• tab_bar.py custom draw function: kitty calls draw_tab() for each tab. is_last=True is the hook for drawing right-aligned status
• CPU % uses delta sampling from /proc/stat — first draw shows "..." (no prior sample), subsequent draws show real usage
• kitty @ load-config merges overrides into running instance without restart
• remote_control from a keymap runs inside kitty's process — no socket/listen_on needed
• Kitty does NOT hot-reload tab_bar.py, font changes, or keybindings — full restart required
• Ctrl+Shift+F5 only reloads colors/visuals
• toggle_tab_bar action does NOT exist in kitty 0.41.1
• set-option RC command does NOT exist — use load-config --override instead
• load-config-file is wrong command name — correct is load-config
• Nerd Font installed system-wide at /usr/local/share/fonts/NerdFonts/

What was tried and didn't work

• headerbar * with min-height: 0 — didn't equalize sidebar/main headerbar heights
• headerbar > windowhandle > centerbox targeting — no effect on height mismatch
• wayland_titlebar_color in kitty — ignored when Mutter uses server-side decorations
• border: none on headerbar — doesn't remove the gray line at top (it's not a headerbar border)
• border-radius: 0 !important on window, window.csd, decoration, .titlebar — doesn't remove rounded corners (Mutter compositor-level clipping)
• GNOME Shell theme .window-frame { border-radius: 0 } — doesn't control Mutter's window corner rounding
• GTK_DEBUG=interactive on Nautilus — inspector window doesn't open (GNOME 48, Nautilus 48.3). Ctrl+Shift+D/I also failed. Shell restart required for newly installed extensions.
• draw_tab_with_powerline — creates clipping artifacts with long tab titles (extra rectangle gets cut off)
• toggle_tab_bar kitty action — doesn't exist in 0.41.1
• remote_control set-option — not a valid RC command
• remote_control load-config-file — wrong name, correct is load-config
• map ctrl+shift+f1 — produces capital P instead of triggering action (escape sequence issue)
• Toggle via background script + kitty @ + socket — overcomplicated, socket discovery unreliable from background processes
• listen_on unix:/tmp/kitty-{kitty_pid} + script with kitty @ --to — still failed, too many moving parts

Debugging notes (2026-04-07)

• Nautilus widget tree (from gresource): NautilusWindow (AdwApplicationWindow) → AdwOverlaySplitView → sidebar: AdwToolbarView → AdwHeaderBar; content: AdwToolbarView → NautilusToolbar (AdwBin) → AdwHeaderBar with title = GtkBox containing NautilusPathBar in a GtkStack
• The main headerbar height was driven by NautilusPathBar's default min-height/padding in the GtkStack
• The gray top line was from the CSD decoration node and/or toolbarview > .top-bar border