i3wm Cheatsheet

Everything is a tree

i3 represents your entire screen as a single tree. Every node in that tree is called a container. Containers with children arrange those children on screen according to a layout rule. Containers without children — the leaves — hold actual application windows. That's the whole model.

The top of the tree is always the same fixed structure. The root node sits at the very top. Below it, one node per physical monitor (i3 calls these outputs). Below each output, the workspaces you switch between with $mod+1, $mod+2, and so on. Below the active workspace is where you work.

Layouts

A container's only job is to declare a layout — a rule that controls how its children are positioned and sized. There are four layouts in i3:

splith

Children are tiled left to right, each taking equal width. The default when you open windows.

splitv

Children are tiled top to bottom, each taking equal height. Triggered with $mod+v before opening.

tabbed

All children share the same space. A horizontal tab bar shows their titles; only the focused one is visible. Toggle with $mod+w.

stacked

Same as tabbed but the title list is a vertical stack instead of a horizontal bar. Toggle with $mod+s.

The layout attribute lives on the container, not on the windows inside it. When you press $mod+w to switch to tabbed, you are changing the layout property of whichever container is the parent of the focused window. Every sibling in that container immediately becomes a tab. Switch back to $mod+e (splith/splitv toggle) and they tile again — the same tree, different rendering.

Splitting

Pressing $mod+v or $mod+b does not immediately change anything visible. It marks the focused window so that the next window you open will land inside a newly created container that wraps the current one. Split and open are two separate actions.

Suppose Terminal is the only window in your workspace. You press $mod+v, then open Neovim. i3 creates a new splitv container, moves Terminal inside it, then places Neovim as a sibling in that container.

This is why trees can grow arbitrarily deep. Every split adds exactly one level of nesting. You can have a splitv container inside a splith container inside a tabbed container — each with its own independent layout.

Focus

The focused window is always a leaf. i3 tracks a focused path — a chain of nodes from the root down to exactly one leaf. Every container along this path also has focus, in the sense that it knows which of its children is in the focused chain.

When you navigate with $mod+h/j/k/l or $mod+Arrow, you move focus to an adjacent leaf within the same parent container. If you reach the edge of the container, focus crosses into the nearest container in that direction. This is why navigation in i3 feels spatial: the tree's structure determines the neighborhood of any given window.

For tabbed and stacked containers, focus controls more than highlighting — it determines which child is rendered. All other children are hidden. Changing focus within a tabbed container is equivalent to switching tabs.

Each internal container remembers which of its children was last focused. If focus moves into a container from outside, i3 restores that container's remembered focus rather than defaulting to the first child. This makes workspace switching and tab navigation feel consistent — returning to a workspace always lands you on the window you were last using.

Nesting — the hidden trap

Every time you tab ($mod+w) then untab ($mod+e), i3 creates a new container level. Repeat this a few times and your windows are buried many levels deep. Then $mod+a needs many presses to reach the right parent.

Avoid toggling tab/split repeatedly. Set up your layout once and leave it. If nesting gets out of hand, press $mod+Shift+f to flatten the workspace — it moves all windows out and back to reset the tree to a single level.

The core rule

To change a group's layout: focus a window inside the group, press $mod+w/e/s directly.

Don't press $mod+a before layout commands — it moves focus up, so the command operates one level higher than intended.

The mental model

You start with a blank workspace: one container. Every window you open becomes a child of the container that currently holds focus. $mod+v or $mod+b followed by opening a window inserts a new container node, creating a sub-region with its own layout.

$mod+v

Next new window opens below (no visual change).

$mod+b

Next new window opens to the right (no visual change).

$mod+w

Tabs siblings. Focus a window in the group, press directly.

$mod+s

Stacks siblings. Focus a window in the group, press directly.

$mod+e

Toggles siblings H/V. Focus a window in the group, press directly.

$mod+a / $mod+z

Move focus up/down the tree. For moving windows, not layout changes.

$mod+Shift+f

Flatten workspace — reset all nesting.

$mod+o

Move current workspace to the other monitor (toggles between outputs).

$mod+Shift+o

Gather all workspaces to current monitor.

auto-pin

i3 config pins ws 2–6 to the external (HDMI-1 / DP-1), ws 1 to the laptop. Connect the dock at home or office and they migrate automatically; undock and they fall back to eDP-1.

$mod+Shift+v

Toggle the AWS VPN window between sticky-visible (follows you across all workspaces) and hidden in scratchpad. Same gesture in both directions. Polybar's VPN icon is the click-to-toggle equivalent.

VPN status

Polybar indicator color reflects state: green = connected, gray = disconnected, red = AWS VPN service is down. Detection: acvc-openvpn process active means connected.

i3tree

Terminal command — shows the container tree for debugging.

$mod+Shift+p

Relaunch polybar (if missing on a monitor).

$mod+Ctrl+k

Re-apply keyboard layout (if Alt+Shift stops working).

When confused, run i3tree to see the tree, and $mod+Shift+f to reset. Every action is a tree operation.