i3 Workspace Groups

A Python library and set of command line tools for managing i3wm workspaces in groups that you define. I find this tool useful for managing many workspaces in i3.

Table of Contents

• Background
• Installation
• Configuration
  • i3 config
  • i3-workspace-groups configuration file
• Usage
  • Example walk through
• Concepts
  • Active workspace
  • Active group
  • Focused group
  • Default group
• Limitations
  • Sway compatibility

Background

I 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 want

  Super+1

  to 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 the i3-workspace-groups project, which enables you to define and manage groups of workspaces, each with their own "namespace", and switch between them.

Installation

The scripts can be installed using pip:

python3 -m pip install i3-workspace-groups

Then you should be able to run the command line tool

i3-workspace-groups

• i3-assign-workspace-to-group

• i3-focus-on-workspace

• i3-move-to-workspace

• i3-rename-workspace

• i3-switch-active-workspace-group

Configuration

i3 config

In order to use these tools effectively, commands need to be bound to keybindings. For example, my i3 config contains the following exerts:

set $mod Mod4

set $exec_i3_groups exec --no-startup-id i3-workspace-groups

# Switch active workspace group
bindsym $mod+g exec --no-startup-id i3-switch-active-workspace-group

# Assign workspace to a group
bindsym $mod+Shift+g exec --no-startup-id i3-assign-workspace-to-group

# Select workspace to focus on
bindsym $mod+w exec --no-startup-id i3-focus-on-workspace

# Move the focused container to another workspace
bindsym $mod+Shift+w exec --no-startup-id i3-move-to-workspace

# Rename/renumber workspace. Uses Super+Alt+n
bindsym Mod1+Mod4+n exec --no-startup-id i3-rename-workspace

bindsym $mod+1 $exec_i3_groups workspace-number 1
bindsym $mod+2 $exec_i3_groups workspace-number 2
bindsym $mod+3 $exec_i3_groups workspace-number 3
bindsym $mod+4 $exec_i3_groups workspace-number 4
bindsym $mod+5 $exec_i3_groups workspace-number 5
bindsym $mod+6 $exec_i3_groups workspace-number 6
bindsym $mod+7 $exec_i3_groups workspace-number 7
bindsym $mod+8 $exec_i3_groups workspace-number 8
bindsym $mod+9 $exec_i3_groups workspace-number 9
bindsym $mod+0 $exec_i3_groups workspace-number 10

bindsym $mod+Shift+1 $exec_i3_groups move-to-number 1
bindsym $mod+Shift+2 $exec_i3_groups move-to-number 2
bindsym $mod+Shift+3 $exec_i3_groups move-to-number 3
bindsym $mod+Shift+4 $exec_i3_groups move-to-number 4
bindsym $mod+Shift+5 $exec_i3_groups move-to-number 5
bindsym $mod+Shift+6 $exec_i3_groups move-to-number 6
bindsym $mod+Shift+7 $exec_i3_groups move-to-number 7
bindsym $mod+Shift+8 $exec_i3_groups move-to-number 8
bindsym $mod+Shift+9 $exec_i3_groups move-to-number 9
bindsym $mod+Shift+0 $exec_i3_groups move-to-number 10

# Switch to previous/next workspace (in all groups).
bindsym $mod+p workspace prev
bindsym $mod+n workspace next

bar {
  strip_workspace_numbers yes
  # The rest of your bar config goes below.
  # ...
}

i3-workspace-groups configuration file

i3-workspace-groups has an optional config file located at

$XDG_CONFIG_HOME/i3-workspace-groups/config.toml

~/.config/i3-workspace-groups/config.toml

Usage

The main operations the CLI tool

i3-workspace-groups

• Assign the focused workspace to a group with a given name (and creating the group if it doesn't exist).
• Switch the currently active group. Note that the active group is not necessarily the same as the focused 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 workspace

mail

work

work:mail

Example walk through

NOTE: This walk through assumes that you configured keybindings like the example i3 config.

Say we start with the following workspace names:

1. 1

   with cat videos from YouTube.

2. 2

   with a news reader.

3. 3

   with a photo editor.

4. 4

   with 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 the default group, which is denoted as

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 workspace

4

Super+Shift+g

work

work

work:4

Super+g

work

work:4

1

2

3

work

work:mail

work

Then, you decide that you want to open a new terminal window in a new workspace. So you press

Super+2

work:2

2

2

Super+2

work

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 press

Super+g

1

2

3

work:4

1

Super+2

2

Concepts

Active workspace

The 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 group

The active group is the group of the active 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 group

The group of the focused workspace.

Default group

The group of workspaces that were not assigned to a group by the user. This group is displayed as

Limitations

• Interaction 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.
• Number of monitors/groups/workspaces: Supports up to 10 monitors, each containing up to 100 groups, each containing up to 100 workspaces.

Sway compatibility

This project depends on i3ipc for 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.