SWAYSOME(1)

📦
version 2.3.2 · 2 versions
, in ubuntu resolute, ubuntu stonking

✨ NAME ✨

SWAYSOME(1) — it's in the User Commands section of your manual, and it's called swaysome, and it does exactly one gorgeous thing: improve multi-output handling on sway. 💖

🌸 SYNOPSIS 🌸

swaysome [OPTIONS] <COMMAND>

that's it. that's the whole vibe. options, then a command. 🎀

🦋 DESCRIPTION 🦋

okay bestie, sit down, because swaysome is about to make your sway setup act a little more like AwesomeWM (https://awesomewm.org/). 🫶

what that means in practice: your "workspaces" get namespaced into things called "workspace groups", and those groups can be yeeted around your different outputs whenever you want. no cap.

here's the moment it clicks. say you've got workspace 11 chillin' on the first output and workspace 21 on the second. you hit your swaysome focus 1 shortcut hoping for workspace 1. what you actually get is workspace 11 if your focus is on the first output, and workspace 21 if the focus is on the second one. iconic behavior, honestly. 💅

by default, swaysome init makes one workspace group per active output. but you're not locked in — you can make more groups while you're working, either by hitting swaysome focus-group <new-number> and then opening a new window, or by sending an existing window over first with swaysome move-to-group <new-number>. chef's kiss. 😌

here's a common use-case, and honestly it ate:

output-1:
    workspace group 1:
        workspace 11: chats
        workspace 12: emails
output-2:
    workspace group 2:
        workspace 21: IDE for first project
        workspace 22: browser for first project
        workspace 23: terminals for first project
    workspace group 3:
        workspace 31: IDE for second project
        workspace 32: browser for second project
        workspace 33: terminals for second project

so the way that works is: when output-2 is focused on workspace group 2 — doesn't matter if it's workspace 21 or 22 — your quick $mod+<number> shortcut (that's the one bound to swaysome focus <number>) won't leave workspace group 2. which means you can run multiple projects in parallel without the absolute hassle of manually remembering how you namespaced them all. no more brain damage fr fr. 🧠✨

now, plot twist: suppose you plug in a new output, output-3. you probably wanna focus workspace group 3 so you can send it over to output-3. how? literally just type the shortcuts $mod+Alt+3 (that's swaysome focus-group 3) and then $mod+Alt+o (that's swaysome workspace-group-next-output). done. slay. 🔥

a couple of housekeeping notes:

  • swaysome may also work with i3, but this is untested. patches welcome if needed. 🙈
  • swaysome should be compatible with sworkstyle (https://lib.rs/crates/sworkstyle). if this is broken, please report a bug. 🐛

💜 USAGE 💜

so, depends on how you got here.

if you installed swaysome from your distribution's package manager, it should have handed your system the default configuration file already. in that case you can just include it from your sway configuration by appending this:

include /etc/sway/config.d/swaysome.conf

otherwise, if you installed it any other way, copy the swaysome.conf file into ~/.config/sway/config.d/swaysome.conf, then append your sway configuration with this:

include ~/.config/sway/config.d/sway.conf
👀 heads up: yes, that second one says sway.conf and not swaysome.conf. that's what the page says, so that's what you get. copy it exactly, bestie.

on the next startup of sway, you should end up with workspaces from 1 to 0, prefixed with a screen index. so you get workspace 11 on the first screen and workspace 21 on the second one, and both are reachable with the shortcut $mod+1 when you're focused on the right output. 🌈

👑 COMMANDS 👑

  • init INDEX — initialize the workspace groups for all the outputs on workspace INDEX. this command just walks through every screen and sets up a prefixed workspace. and the way it does it is backwards, so that you end up focused on the first screen, as usual. cute, right?
  • move INDEX — move the focused container to workspace INDEX (and stay in the same workspace group).
  • move-to-group INDEX — move the focused container to workspace group INDEX (and keep the same workspace index).
  • focus INDEX — focus to workspace INDEX (and stay in the same workspace group).
  • focus-group INDEX — focus to workspace group INDEX (and keep the same workspace index).
  • focus-all-outputs INDEX — focus to workspace INDEX on all the outputs at once. ngl, there's no keyboard shortcut bound by default for this function, so you'll have to call it yourself.
  • next-output — move the focused container to the next output.
  • prev-output — move the focused container to the previous output.
  • workspace-group-next-output — move the focused workspace group to the next output.
  • workspace-group-prev-output — move the focused workspace group to the previous output.
  • next-group — move the focused container to the next group.
  • prev-group — move the focused container to the previous group.
  • rearrange-workspaces — rearrange already opened workspaces to the correct outputs. genuinely so useful when you're plugging in new monitors. 🔌
  • help — print this message or the help of the given subcommand(s).

🎀 OPTIONS 🎀

  • -h, --help — print help.
  • -V, --version — print version.

⭐ VERSION ⭐

2.3.2

🌸 HOMEPAGE 🌸

https://gitlab.com/hyask/swaysome

please report any bug or feature requests on the bug tracker. 🫶

💅 AUTHORS 💅

Florent 'Skia' Jacquet <skia@hya.sk>

and that's the whole page, bestie — this was swaysome 2.3.2, dated Sep 2025, and it lives in the User Commands section of your manual. go forth and namespace your workspaces. periodt. 💖✨🎀🦋

📦 where this page comes from