How to configure Special Workspace Toggles?

[NickyRak]

Inside my keybinds.conf I have this section:

Special workspace toggles

bind = $kbSystemMonitor, exec, caelestia toggle sysmon
bind = $kbMusic, exec, caelestia toggle music
bind = $kbCommunication, exec, caelestia toggle communication
bind = $kbTodo, exec, caelestia toggle todo

for example I want to use Teams-for-linux as my default Communication app and P3X-OneNote for my Todo app

Can you help me please?

[soramanew]

See the configuring section in the cli readme

[NickyRak]

When I try to open the "~/.config/caelestia/cli.json" it's just blank not like in the readme. I don't know if it is on different directory

[soramanew]

You add your own configs to it. The one shown in the readme is an example containing all the default configs

[NickyRak]

Thanks a lot, sir! I am new to Arch Linux, sorry if it was obvious ¯_(ツ)_/¯

[romanvesely]

I ran into the same confusion and only got it working after quite a bit of trial and error. What finally made it click is that Special Workspace toggles require configuration in four different places, not just keybinds.

Here’s a complete, working setup.

1️⃣ keybinds.conf – define the toggle actions

You need to bind the toggle commands themselves, not workspace switches:

# Special workspace toggles
bind = $kbSystemMonitor, exec, caelestia toggle sysmon
bind = $kbMusic, exec, caelestia toggle music
bind = $kbCommunication, exec, caelestia toggle communication
bind = $kbChatgpt, exec, caelestia toggle chatgpt
bind = $kbTeams, exec, caelestia toggle teams

2️⃣ variables.conf – define the key combinations

Make sure the variables referenced above actually exist:

# Special workspace toggles
$kbSystemMonitor = Ctrl+Shift, Escape
$kbMusic = Super, M
$kbCommunication = Super, D
$kbChatgpt = Super, R
$kbTeams = Super, T

3️⃣ rules.conf – assign windows to special workspaces

This part is mandatory so Hyprland knows where the windows belong:

# Special workspaces
windowrule = workspace special:sysmon, match:class btop
windowrule = workspace special:music, match:class tidal-hifi
# windowrule = workspace special:music, match:initial_title Spotify( Free)?  # Spotify Wayland workaround
windowrule = workspace special:communication, match:class signal
windowrule = workspace special:chatgpt, match:class chat-gpt
windowrule = workspace special:teams, match:class teams-for-linux

4️⃣ Critical step – create cli.json for Caelestia

This is the part that’s easy to miss:
You must create a .config/caelestia/cli.json (next to shell.json).
Without this, the toggles won’t actually launch or move apps.

Example working config:

{
  "toggles": {
    "communication": {
      "discord": { "enable": false },
      "whatsapp": { "enable": false },
      "signal": {
        "enable": true,
        "match": [{ "class": "signal" }],
        "command": ["signal-desktop"],
        "move": true
      }
    },
    "chatgpt": {
      "chat-gpt": {
        "enable": true,
        "match": [{ "class": "chat-gpt" }],
        "command": ["chat-gpt"],
        "move": true
      }
    },
    "music": {
      "tidal-hifi": {
        "enable": true,
        "match": [{ "class": "tidal-hifi" }],
        "command": ["tidal-hifi"],
        "move": true
      }
    },
    "teams": {
      "teams-for-linux": {
        "enable": true,
        "match": [{ "class": "teams-for-linux" }],
        "command": ["teams-for-linux"],
        "move": true
      }
    }
  }
}

Once everything is wired together, the behavior is rock solid and does exactly what you’d expect. Hope this saves someone else a few hours of head-scratching 🙂

[evertiro]

FYI, if you edit keybinds.conf, variables.conf, and rules.conf your changes will be lost on updates. You don't have to edit any of those files though. All the changes you'd make in those files can be made through the hypr-user.conf and hypr-vars.conf files that aren't overwritten on updates.

[romanvesely]

That’s indeed a very interesting hint, thanks for pointing it out. I had already been wondering what the intended workflow and structure behind this setup actually is.

Is there a recommended way to organize things between hypr-user.conf and hypr-vars.conf, or is it perfectly fine to keep this rather pragmatic like defining variables in one file and then freely mixing configuration, rules, and keybinds in the other without a strict separation?

I’d be curious to know whether there’s an intended convention here, or whether the flexibility is deliberate.

[soramanew]

The difference between hypr-user.conf and hypr-vars.conf is that hypr-vars.conf is sourced before most of the default config, so the changes you make to variables there will be reflected in the config. This is where you should put your variable definition overrides (e.g. you could copy variables.conf over to it and tweak the values). On the other hand, hypr-user.conf is sourced after the default config, and is where you should put most if not all of your custom configs.

[soramanew]

You can always source other files from either one, so if you'd like to keep your custom configs organised into multiple files, you can.

[romanvesely]

Thank you. I think I now managed to set it up the right way. Anyway trying to make changes like displaying the 24H format does not work, when I put it into the cli.json instead of the shell.json. But if I am gonna update the shell in the future, the shell.json will be overwritten, won´t it?

[phirrehan]

no the shell.json does not get overwritten. it will stay as it is unless you decide to change it. you won't need to worry about it until the example shell.json from README.md gets updated.

[evertiro]

Even then it won't likely be an issue unless how an option is handled changes or an option is removed

[soramanew]

Breaking changes to the config will be announced in the discord server

[Mordius]

I don't know if this is the right place to ask, please tell me if a have to create a new issue/discussion.

I've got shell.json configured like this:

   "toggles": {
    "communication": {
     "discord": { 
      "enable": true,
      "match": [{ "class": "discord" }],
      "command": [ "discord --ozone-platform-hint=wayland" ],
      "move": true
        }
       },
    "games": {
      "steam": {
      "enable": true,
      "match": [{ "class": "steam" }],
      "command": [ "steam" ],
      "move": true
        }
      }  
    } 

Discord works perfectly but for some reason steam launches in big picture using gamescope instead of normal steam window. I commented steam's window rules in the rules.conf inside .config/hypr/hyprland folder, and set my own in hypr-vars.conf (also tried hypr-user.conf with the same result). When removing the gamescope package steam won't launch anymore, not even in big picture (it launches normally if I use the .desktop file or from terminal)

[evertiro]

I don't know if this is the right place to ask, please tell me if a have to create a new issue/discussion.

I've got shell.json configured like this:

   "toggles": {
    "communication": {
     "discord": { 
      "enable": true,
      "match": [{ "class": "discord" }],
      "command": [ "discord --ozone-platform-hint=wayland" ],
      "move": true
        }
       },
    "games": {
      "steam": {
      "enable": true,
      "match": [{ "class": "steam" }],
      "command": [ "steam" ],
      "move": true
        }
      }  
    } 

Discord works perfectly but for some reason steam launches in big picture using gamescope instead of normal steam window. I commented steam's window rules in the rules.conf inside .config/hypr/hyprland folder, and set my own in hypr-vars.conf (also tried hypr-user.conf with the same result). When removing the gamescope package steam won't launch anymore, not even in big picture (it launches normally if I use the .desktop file or from terminal)

Generally, you'd want to create a new issue. That said, the toggles config doesn't actually go in shell.json, it goes in cli.json. Discord is working fine because it's enabled by default.

[Mordius]

Thanks, I'm blind, actually I have the cli.json file with steam configured to launch in big picture with gamescope.... I think I did that 2 months ago but never ended up using it and I forgot. Thanks again

[evertiro]

No problem