Hide single titlebar in Sway window manager

by

Summary

The user is asking about a Sway window manager configuration challenge: hiding the titlebar when only a single window exists on screen, while retaining titlebar visibility for multi-window layouts. The user currently has titlebars enabled for active window distinction (via colors) but wants to suppress them when the workspace is not split. Standard solutions typically address border hiding or gap management, but this request targets a specific conditional UI element (titlebar) behavior.

Root Cause

The root cause is a limitation in Sway’s IPC (Inter-Process Communication) event granularity and criteria matching.

  • Static Configuration: Sway configuration is largely static. While titlebar_border_thickness and titlebar_padding allow visual tuning, they cannot be dynamically toggled based on the number of windows in a container without external scripting.
  • Lack of “Single Window” Event: Sway’s IPC events (e.g., window, workspace) do not emit a specific signal for “container count changed from 1 to 2.” Consequently, a purely swaymsg-based configuration cannot react to the split state of a container automatically.
  • Criterion Gap: for_window criteria in Sway match window properties (class, app_id, etc.) or states (floating, tiled), but they cannot match the siblings of a window (i.e., “is this window the only child of its parent?”).

Why This Happens in Real Systems

In production systems engineering, this mirrors the C10K problem (handling 10,000 concurrent clients) but applied to UI state management.

  • State Explosion: To handle every possible UI state (1 window, 2 windows, 3 windows, floating windows, stacked tabs), the configuration complexity grows exponentially. Most window manager developers prioritize tiling logic over conditional decoration, as decoration is often handled by the application toolkit (GTK, Qt) or a separate compositor (e.g., Wayfire, Hyprland).
  • Performance vs. Responsiveness: Dynamic UI updates (changing CSS/geometry on every window layout change) incur CPU cycles. Sway maintains a strict separation of concerns: it manages layout (geometry) and delegates drawing where possible. Patching the rendering loop to check decoration visibility per frame would violate the lean architecture principles of the wlroots ecosystem.

Real-World Impact

  • Visual Noise: Retaining a titlebar on a single window reduces the effective screen real estate (pixel economy), which is critical for high-DPI displays or developer workflows using terminal multiplexers.
  • Workflow Interruption: Users rely on visual anchors. A titlebar indicates “active” status. When a single window is maximized, the titlebar becomes redundant data (the window is clearly active), yet it occupies space.
  • Configuration Fragility: Relying on external scripts to detect window counts introduces race conditions. If the script polls too fast, it lags; if it polls too slow, the UI state desynchronizes.

Example or Code

To achieve this, we must implement a reactive listener using swaymsg -t subscribe to monitor the window and workspace events. This script parses the JSON output to determine if a workspace contains exactly one window.

Here is a Python implementation (requires i3ipc or standard JSON parsing) or a shell-based approach. Below is a shell-based proof of concept executable as a background daemon:

#!/bin/bash

# Function to check single window state
check_windows() {
    # Get tree and count visible tiling windows on focused workspace
    local count
    count=$(swaymsg -t get_tree | jq '[.. | select(.type?" == "con" and .visible? == true and .workspace?" != "__i3_scratch")]' | jq 'length')

    if [ "$count" -eq 1 ]; then
        # Hide titlebar for single window
        swaymsg "gaps inner current set 0; titlebar_border_thickness 0; titlebar_padding 0 0"
    else
        # Restore titlebar for split layouts
        swaymsg "gaps inner current set 3; titlebar_border_thickness 0; titlebar_padding 5 1"
    fi
}

# Initial check
check_windows

# Listen for changes
swaymsg -t subscribe -m '["window","workspace"]' | while read -r line; do
    check_windows
done

How Senior Engineers Fix It

Senior engineers approach this via event-driven automation rather than native feature requests, ensuring the solution is portable and agnostic to window manager updates.

  1. External Daemon Approach: Run a lightweight background script (like the one above) that subscribes to Sway’s IPC. This decouples the logic from the window manager core.
  2. Polling vs. Blocking: Use swaymsg -t subscribe (blocking read) rather than a cron job or while loop with sleep. This ensures zero-latency reaction to layout changes (splitting or merging containers).
  3. State Validation: The script must strictly validate the state. It should not just count windows, but ensure it is counting tiling windows on the current workspace, ignoring floating windows or scratchpad containers.
  4. Idempotency: Ensure the swaymsg commands are idempotent (running them twice has the same effect as once) to prevent configuration drift.

Why Juniors Miss It

Juniors often approach this problem from a declarative mindset rather than a programmatic mindset.

  • Searching for Native Flags: Juniors typically search for a single config flag (e.g., smart_titlebar on). They miss that Sway is a tiling manager, not a floating window manager with complex decoration rules; it assumes the user wants visibility over single windows or utilizes Tabbed/Stacked layouts.
  • Ignoring IPC Capability: Many users are unaware that swaymsg can subscribe to events. They assume configuration files are static and the only dynamic control is via key bindings.
  • Overlooking JSON Parsing: The Sway tree structure is complex JSON. Juniors often try to parse this with brittle grep/awk chains, failing on edge cases (nested containers, floating windows), whereas a robust solution requires a proper JSON parser (jq, python).