Package: i3-workspace-groups
i3 Workspace GroupsA Python library and set of command line tools for managing i3wm workspaces in
groups. I find this tool useful for managing many workspaces in i3.Table of ContentsBackgroundInstallationConfigurationi3i3-workspace-groupsUsageExample walk throughConceptsActive workspaceActive groupFocused groupDefault groupLimitationsSway compatibilityPolybarBackgroundI often find myself working with many i3 workspaces at once (7-8+), usually
related to multiple projects/contexts (personal/work etc). This has caused me a
few issues, for example:Working with a set of workspaces of a given project/context, without being
distracted by unrelated workspaces.Reusing the same workspace number in multiple projects/contexts. For example,
I have two different emails for personal and work stuff, and I wantSuper+1to always switch to the workspace with the email client relevant to my current
context.Finding a free workspace for a new window (that can also be reached with my
keybindings)This has led me to create thei3-workspace-groupsproject, which enables you to define and manage groups of workspaces, each with
their own "namespace", and switch between them.InstallationThe scripts can be installed using pip:python3-mpipinstalli3-workspace-groupsThen you should be able to run the command line tooli3-workspace-groups. There are also a few utility
scripts provided that requirerofiand
which are useful for interactively managing the groups, using rofi as the UI.
They include:i3-assign-workspace-to-groupi3-focus-on-workspacei3-move-to-workspacei3-rename-workspacei3-switch-active-workspace-groupIf you want to use client/server mode for improved speed/latency, it's
recommended to install one of the following tools to further improve speed:socat: available in all major distrosBSD netcat (GNU version not supported)ncatConfigurationi3In order to use these tools effectively, commands need to be bound to
keybindings. For example, my i3 config contains the following exerts:set $mod Mod4set $exec_i3_groups exec --no-startup-id i3-workspace-groups# Switch active workspace groupbindsym $mod+g exec --no-startup-id i3-switch-active-workspace-group# Assign workspace to a groupbindsym $mod+Shift+g exec --no-startup-id i3-assign-workspace-to-group# Select workspace to focus onbindsym $mod+w exec --no-startup-id i3-focus-on-workspace# Move the focused container to another workspacebindsym $mod+Shift+w exec --no-startup-id i3-move-to-workspace# Rename/renumber workspace. Uses Super+Alt+nbindsym Mod1+Mod4+n exec --no-startup-id i3-rename-workspacebindsym $mod+1 $exec_i3_groups workspace-number 1bindsym $mod+2 $exec_i3_groups workspace-number 2bindsym $mod+3 $exec_i3_groups workspace-number 3bindsym $mod+4 $exec_i3_groups workspace-number 4bindsym $mod+5 $exec_i3_groups workspace-number 5bindsym $mod+6 $exec_i3_groups workspace-number 6bindsym $mod+7 $exec_i3_groups workspace-number 7bindsym $mod+8 $exec_i3_groups workspace-number 8bindsym $mod+9 $exec_i3_groups workspace-number 9bindsym $mod+0 $exec_i3_groups workspace-number 10bindsym $mod+Shift+1 $exec_i3_groups move-to-number 1bindsym $mod+Shift+2 $exec_i3_groups move-to-number 2bindsym $mod+Shift+3 $exec_i3_groups move-to-number 3bindsym $mod+Shift+4 $exec_i3_groups move-to-number 4bindsym $mod+Shift+5 $exec_i3_groups move-to-number 5bindsym $mod+Shift+6 $exec_i3_groups move-to-number 6bindsym $mod+Shift+7 $exec_i3_groups move-to-number 7bindsym $mod+Shift+8 $exec_i3_groups move-to-number 8bindsym $mod+Shift+9 $exec_i3_groups move-to-number 9bindsym $mod+Shift+0 $exec_i3_groups move-to-number 10# Switch to previous/next workspace (in all groups).bindsym $mod+p workspace prevbindsym $mod+n workspace nextbar {strip_workspace_numbers yes# The rest of your bar config goes below.# ...}i3-workspace-groupsi3-workspace-groups has an optional config file located at$XDG_CONFIG_HOME/i3-workspace-groups/config.toml(defaults to~/.config/i3-workspace-groups/config.toml). See thedefault config filefor all the possible
options to configure, their meaning, and their default values.UsageThe main operations the CLI tooli3-workspace-groupssupports are:Assign the focused workspace to a group with a given name (and creating the
group if it doesn't exist).Switch the currentlyactive group. Note that the active group
is not necessarily the same as thefocused group.Navigation and movement within a group while ignoring the other groups. See
examples below.The tools provided use i3 workspace names to store and read the group for each
workspace. For example, if a user assigns the workspacemailto the groupwork, it will be renamed towork:mail.Example walk throughNOTE:This walk through assumes that you configured keybindings like theexample i3 config.Say we start with the following workspace names:1with cat videos from YouTube.2with a news reader.3with a photo editor.4with an email client for work.An important thing to understand here is that every i3 workspace is always
assigned to a single group. And since we haven't assigned any workspace to a
group yet, all the workspaces are implicitly in thedefault group, which is denoted as<default>.After a few hours of leisure time, you decide to do some work, which requires
opening a few windows on a few workspaces. In order to create a new group, first
you switch to the workspace4, and then you pressSuper+Shift+g, which will
prompt you for a group to assign to the current workspace. You typeworkand
press enter. Since there's no group namedworkyet, the tool will create it
and assign the focused workspace to it. You will then notice that the workspace
name will change in i3bar towork:4. Then, you pressSuper+gin order to
switch theactive group. You will be shown a list of existing
groups, which will now beworkand<default>. You should now see your
workspaces in i3bar ordered as following:work:4,1,2,3. What happened
here? When you switched to theworkgroup, the first thing that the tool did
was to move all the workspaces in the work group (onlywork:mail) to be in the
beginning of the workspace list. Then, it renamed the workspaces in the default
group to include the group name, so that they can be differentiated from other
workspaces in theworkgroup with the same name.Then, you decide that you want to open a new terminal window in a new workspace.
So you pressSuper+2, which will move you to a new workspace namedwork:2.
Note that although there is already a workspace with the name2in the default
group (now shown as2in the workspace list), usingSuper+2actually takes
you to a new empty workspace in the groupwork.After some time working, you become lazy and you want to get back to cat videos,
but you promise yourself to get back to work in a few hours, and you don't want
to lose your open windows. So you pressSuper+gto switch the active work back
to the default one. You should now see your workspaces in i3bar ordered as
following:1,2,3,work:4. The focus will also shift to the first
workspace in the default group (1in this case). Now that you're back in the
default group, pressingSuper+2will again lead you to the workspace2in
the default group.ConceptsActive workspaceThe active workspace is the workspace with the lowest number. Typically, this
will be the workspace that appears first in the workspace list in i3bar (the
leftmost one).NOTE:In a multi-monitor setup, there is an active workspace per monitor.NOTE:The active workspace is not necessarily the focused workspace.Active groupThe active group is the group of theactive workspace. This
group will normally contain workspaces related to the task you're doing at the
time it's active. When you want to work on another task, you can switch the
active group. Workspaces that are not in the active group can still be
interacted with, but some commands provided are designed to make it easier to
interact with the workspaces of the active group.NOTE:In a multi-monitor setup, there is an active group per monitor.Focused groupThe group of the focused workspace.Default groupThe group of workspaces that were not assigned to a group by the user. This
group is displayed as<default>. When you start using i3-workspace-groups,
none of your current workspaces will be assigned to a group yet, so they will
all be in the default group.LimitationsInteraction with other i3 tools: workspace names are used for storing the
group, so if another tool changes a workspace name without preserving the
format that i3-workspace-groups uses, i3-workspace-groups can make a mistake
about the group assignment.Latency: there can be noticeable latency in some machines for the script
commands. On my high performance desktop this is not noticeable, but on my
laptop it is. I measured the latency of commands to be around 100-200 ms, most
of it coming from importing python libraries, so it's not possible to reduce
it much without running it as a daemon (which will overcomplicate things). In
the long term, I plan to rewrite it in go.UPDATE: there is a new
experimental client/server mode which significantly reduces latency.
Documentation is still WIP (seehttps://github.com/infokiller/i3-workspace-groups/issues/52).Number of monitors/groups/workspaces: Supports up to 10 monitors, each
containing up to 100 groups, each containing up to 100 workspaces.Sway compatibilityThis project depends oni3ipcfor its
interaction with i3, so should also work the same on sway. That said, I don't
test it on sway and i3 is my main window manager.PolybarThe officialinternal/i3module does not support workspace groups.In order to display workspace information in polybar, there are two steps:Add the custom i3 workspace groups module to your polybarRun a script in the background to update polybar's display whenever an i3
window event occurs1. Add the custom i3 workspace groups module to your polybar configCreate ani3-modmodule by adding the following to your polybar config:[module/i3-mod]
type = custom/ipc
hook-0 = ${env:I3_MOD_HOOK}
initial = 1Then, add thei3-modmodule to your modules:modules-center = i3-modThen, when launching polybar, do something like the following to configure theI3_MOD_HOOK:whileIFS=''read-rmonitor;doi3_mod_hook="i3-workspace-groups polybar-hook --monitor '${monitor}'"I3_MOD_HOOK="${i3_mod_hook}"polybaryour-bar-name&done<<(polybar--list-monitors|cut-d':'-f1)2. Run a background script to update polybar's on i3 eventsRun thei3-groups-polybar-module-updaterscript. This script is responsible for calling the hook to update polybar
whenever a relevant i3 window event occurs.