i3bg

i3bg

i3bg is a tool to manage "background workspaces" in i3. It is written in Go and controls i3 via IPC.

Rationale

In i3, I always keep my main browser window in workspace 2 and my main project in workspace 1. When I want to look something up online, I press mod+2, and when I want to continue coding I press mod+1.

This system works great when I am working on exactly one project at a time. But I often want to briefly work on something else in the middle of a project. The natural solution in this case is to go to a different workspace, perhaps workspace 3, and open my windows for the other project there.

Unfortunately, my muscle memory works against me here. I switch to workspace 3, start coding, then I switch to workspace 2 to look something up. When I want to go back to my work, I often press mod+1 and end up in the wrong place.

Now imagine I have 3 additional projects open in workspaces 3, 4, and 5. I end up linearly scanning them to find the right one. Not good -- there must be a better way.

Here is what I really want:

• whatever I am currently working on is in workspace 1, i.e. I can always press mod+1 to get to my current project
• when I want to switch gears and work on something else, I can move my original project to a different ("background") workspace
• It should be very easy to find and "foreground" a project that I have backgrounded.

Installation

Be sure that your $PATH includes $GOPATH/bin (on my system: ~/go/bin).

go install git.sr.ht:~ajpaon/i3bg@latest

Quickstart

i3bg depends on some conventions:

• Give your project workspace a meaningful name. Rather than simply 1, the workspace should be called 1: project. So it is necessary to have a simple way to rename workspaces. In the config below I use mod+Shift+n

• Rather than bindsym $mod+<n> workspace <n>, use bindsym $mod+<n> workspace number <n>. The latter syntax ignores the semantic suffix in the workspace name.

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

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

bindsym $mod+b exec --no-startup-id "i3bg bg-next"
bindsym $mod+Shift+b exec --no-startup-id "i3bg toggle"

# dmenu integration -- see below
bindsym $mod+Control+b exec --no-startup-id "i3bg-dmenu"

bindsym $mod+Shift+n exec i3-input -F 'rename workspace to "%s"' -P 'Name for this workspace (should include "<num>: " prefix): '

Once you have installed the command and added the requisite i3 config:

• mod+b repeatedly to browse backgrounded workspaces
• mod+Shift+b to background or foreground the current workspace
• mod+Shift+n to rename the current workspace (you need to use names prefixed with "1:" or "bg:"

Dmenu integration

i3bg comes with a built-in dmenu integration, which you can run with:

i3bg toggle-dmenu

It allows you to pick a background workspace by name using dmenu.

The starter configuration above binds this command to $mod+Control+b

If you'd rather use fzf, rofi, or some other selection tool, you can build your own on top of these commands:

i3bg bg-list       # to get a list of all background workspaces
i3bg toggle [name] # to toggle a workspace by name

Command

i3bg provides the following commands

i3bg toggle [name]

• when you are focusing the active project workspace, move it to the background
• when you are focusing a background workspace, move it to the foreground. If there is already a foreground workspace, move that one to the background.
• if you provide name, this command operates on the named workspace rather than the focused workspace.

i3bg bg-next

• switch to the background workspace that comes lexicographically next after the current focused workspace.

i3bg bg-list

• write the names of all background workspaces to stdout

i3bg toggle-dmenu

• select a background workspace to toggle using dmenu

Contributing

Please email ~ajpaon/public-inbox@lists.sr.ht with any bugs, feature requests, or patches.