COSMIC Desktop Env: automated window rules?

by

Summary

The user’s question highlights a documentation gap in the COSMIC Desktop Environment regarding automated window rules. As of the latest public documentation, COSMIC’s window management rules (auto-floating, tiling, positioning, sizing) are primarily defined via the cosmic-session settings daemon and the cosmic-comp compositor, which rely on JSON configuration files or database settings. There is no centralized, official user-facing documentation for these rules, so engineering relies on source code analysis and community configuration examples.

Root Cause

The root cause is the immature state of COSMIC documentation compared to mature desktop environments like GNOME or KDE. COSMIC is actively evolving (as of late 2024/early 2025), and its configuration is largely code-driven rather than GUI-driven.

  • The window rule system is part of the compositor (cosmic-comp) and the shell (cosmic-session).
  • Rules are processed by the cosmic-settings daemon or directly by cosmic-comp based on xdg-desktop-portal and window matching heuristics.
  • The primary source of truth for window rules is the cosmic-settings source code and the cosmic-comp configuration logic.

Why This Happens in Real Systems

In real-world desktop environments, window rule automation often suffers from documentation lag because:

  • Development speed > Documentation speed: New features like window rules are implemented in the compositor before UI or docs catch up.
  • Configuration is often file-based: Many advanced window managers (i3, sway, Hyprland) use config files. COSMIC is adopting a similar model for power users.
  • Lack of stable APIs: The underlying wayland protocol and COSMIC’s implementation are still evolving, making it risky to document APIs that might change.

Real-World Impact

  • Users struggle with automation: Without clear docs, users cannot reliably set floating vs. tiling behavior, workspace-specific placement, or initial geometry.
  • Inconsistent behavior: Window rules may fail silently, leading to frustration and abandonment of the desktop environment.
  • Community fragmentation: Users resort to scattered blog posts and GitHub issues for help, leading to inconsistent configurations.

Example or Code

If you need to automatically float specific windows in COSMIC, you can configure this via the cosmic-comp settings (subject to change). Here’s an example configuration approach:

{
  "window_rules": [
    {
      "app_id": "org.gnome.Nautilus",
      "floating": true
    },
    {
      "app_id": "firefox",
      "workspace": 2,
      "floating": false
    }
  ]
}

Note: The exact JSON schema may vary. Check the cosmic-comp GitHub repository for the latest structure.

How Senior Engineers Fix It

Senior engineers address this documentation gap by:

  • Reading the source code: cosmic-comp on GitHub is the primary reference.
  • Checking cosmic-settings schema: The settings app often exposes window rule options via JSON or dconf.
  • Analyzing xdg-desktop-portal-cosmic: This handles window management rules for flatpaks and native apps.
  • Joining community forums: Pop!_OS Matrix/Discord or COSMIC GitHub discussions are where workarounds are shared.
  • Writing their own docs: Publishing technical blog posts or gist snippets to fill the gap.

Why Juniors Miss It

Junior developers or users often:

  • Look for official GUI menus: COSMIC’s settings UI may not expose all window rule options yet.
  • Assume feature parity: They expect COSMIC to have KWin-like or GNOME Mutter-like rule settings.
  • Ignore source code: They don’t realize that the config is code, and the code is the documentation.
  • Rely on outdated guides: Older blog posts (like the one linked) may reference deprecated mechanisms.