Concepts

Planes, tags, gather/summon scratchpads, the overview, anchors, marks, window rules and groups — the primitives you compose into a workflow.

The mental model covers one plane: rows, columns, cells, splits, tabs, floats. This page is everything you build on top of that — the primitives that turn atlaswm from a tiler into a toolbox. None of these is a mode you're locked into; they compose.

Planes

One infinite plane is rarely enough. A plane is a whole independent canvas — its own windows, its own pan position, its own zoom. atlaswm holds a pool of them and shows exactly one at a time: the active plane fills the viewport, the rest sit idle in the background. Switching is instant and lossless — each plane remembers where you left it, so you return to the same windows at the same pan and zoom. Think i3/sway workspaces or niri's named workspaces, except each one is a full 2D atlas rather than a screenful.

The everyday entry point is the planes submap (Mod+o): l/h switch, n creates, q closes an empty plane, Shift+l/Shift+h move the focused window to the next/previous plane and follow it. Plus quick binds outside the submap: Mod+period / Mod+comma.

Two more actions, for binds or atlasctl action:

• plane-switch:<n> — jump to the n-th plane (1-based), creating any planes on the way (the niri/sway dynamic-workspace feel: plane-switch:3 from a single plane lands you on plane 3, having quietly made 2 and 3).
• plane-close — destroy the active plane, but only if it's empty. On a non-empty plane it's a no-op (a plane with windows is never silently torn down).

Window ids stay globally unique across planes, and moving a window between planes keeps its id — same client, same content, new home. Over IPC, atlasctl query planes lists the pool and a per-window plane field tells you each window's home.

Tags

A tag is a free-form label you stick on a window — work, chat, mail, whatever names a working set. Tags are independent of planes and of layout geometry: tagging never moves a window, and the same name can ride on windows scattered across different planes. A window can carry any number of tags; they ride with it by id (moving it, floating it, fullscreening it leaves tags untouched) and drop when it closes.

Four verbs act on the focused window:

• tag-toggle:<name> — add if absent, remove if present.
• tag-add:<name> / tag-remove:<name> — explicit set / unset.
• tag-clear — remove every tag at once.

There are no default tag binds — tag names are yours, so the config can't guess them. Bind your own ("Mod+F1" "tag-toggle:work") or drive them over atlasctl. Tags are also what gather/summon operate on, and what window rules can stamp at open time.

Scratchpads: gather and summon

A tag names a working set; gather and summon let you see that whole set at once — temporarily, without moving anything. Both are a live borrow: nothing leaves its home plane, and dismissing restores everything exactly as it was.

Gather

gather-toggle:<tag> pulls every window carrying <tag> — wherever it lives — into a temporary tiled view that replaces your current view, and that view is fully interactive: focus, resize, move, tab, fullscreen all work in it. Dismiss it (the same tag again, or gather-dismiss) and every plane is restored, each window back where it was. Spawning while gathered lands on the real active plane (so a terminal you open mid-gather isn't lost on dismiss); closing a gathered window closes it everywhere; any plane switch dismisses first.

Summon

Where gather replaces your view, summon-toggle:<tag> overlays it: it floats every window carrying <tag> that lives on another plane over your current plane — a peek at the working set without leaving where you are. A tagged window already on the current plane stays tiled; summon complements it. The summoned windows are ordinary, fully interactive floats. Toggle the same tag (or summon-dismiss) to hide them.

Gather and summon are mutually exclusive — only one scratchpad view at a time. There are no default binds for either; bind your own or use atlasctl.

Overview

A plane fills the viewport; the overview shows them all at once. Toggle it with overview-toggle, or just keep zooming out — one step past fit-plane (Mod+z again at the last rung) opens it, so the ladder runs 100% → 50% → fit → overview. Every plane becomes a live scaled mini-canvas in a grid (windows keep rendering — a watch date keeps ticking), and the active plane wears an accent frame.

It's navigation-only: click any window to jump to its plane focused, or click an empty plane to jump there — the overview closes and you land on a real plane. While it's open the normal binds are inert; only the exits act (Escape, zoom-in, or overview-toggle again). You can also drag a window from one plane's cell to another plane's cell to move it there — the drop-target cell highlights as you drag; a plain click still jumps.

There's no default bind: zooming out past fit-plane is the discoverable path.

Anchors

An anchor is a named viewport bookmark on a plane — a spot you jump back to.

• anchor-set:<name> records the active plane's current view center.
• anchor-jump:<name> re-centers the viewport on it (zoom-independent — the stored value is a plane coordinate).
• anchor-clear:<name> drops it.

Anchors are per-plane: the same name on plane 2 is a different spot than on plane

1. You can seed anchors on plane 1 from the config — useful for a fixed layout you always return to:

anchors {
    "hub"  x=0    y=0
    "mail" x=4000 y=0
}

binds {
    "Mod+a" "anchor-jump:hub"
    "Mod+e" "anchor-jump:mail"
}

This is the backbone of a hub-and-satellite workflow: scatter working sets across one big plane and jump between them by name.

Marks

Marks are vim-style: set a mark on a window, jump back to it later. The name's case picks the scope:

• lowercase = local (per-plane): the same name is a different window on each plane.
• UPPERCASE = global: one session-wide table; the jump follows the window across planes.

mark-set:<name>     mark the focused window
mark-jump:<name>    focus the marked window (switches plane if needed)
mark-clear:<name>   drop the mark

There are no default mark binds; the typical setup is a mark submap to set and a jump submap to jump (so Mod+m a marks, Mod+' a jumps). Marks are runtime only (window identity isn't stable across restarts, so they aren't seeded from config). Marks auto-clear when their window closes.

Related: jump-to-window (jump-to-window) badges every window currently on-screen with a letter; press the letter to focus that window. It's a quick "focus that one" without remembering a mark.

Window rules

Match a window by app-id and/or title (regex) when it opens, and override where and how it lands. Multiple matching rules cascade in document order (later wins on a scalar; tags from all matches union). Rules apply to windows opened after a (re)load.

rules {
    rule {
        match app-id="^(firefox|chromium)$"
        plane 2
        tag "web"
    }
    rule {
        match title=".*Picture-in-Picture.*"
        float #true
        size 480 270
    }
    rule {
        match app-id="Slack"
        open-as-tab #true
        tag "comms"
    }
}

Available overrides: plane <n> (1-based target plane, opened in the background — you stay put), tag "<name>" (repeatable, unions), float #true, size <w> <h> (for floats), open-as-tab #true (join the focused container as a tab). A bad regex is a config error — the last-good config keeps running, and you fix it via live reload. Rules match XWayland (X11) windows too, by their WM_CLASS / title.

Not yet: auto-tagging is the manual tag-* verbs plus these rules; there's no per-app "always open at anchor Y" yet (spawn-at-anchor is deferred). Use a plane <n> rule plus an anchor-jump bind for the closest equivalent today.

Groups

A group is a connected tiled cluster. A plane can hold several disconnected groups — clusters of tiles sitting apart on the canvas, the driftwm-style working-set model.

• spawn-new-group starts a fresh cluster at the viewport top-left.
• group-next / group-prev switch between the clusters on a plane (restoring each group's focus).
• group-to-plane-next / group-to-plane-prev / group-to-plane:<n> move the whole focused group to another plane intact (and follow it). Window ids are unchanged, so tags ride along.
• group-tag-toggle:<name> (and -add / -remove / group-tag-clear) tag every window in the group at once. Because that reuses the tag store, gather/summon on that tag is "temporarily show this whole group" for free.

A natural setup pairs these with a one-shot groups submap:

binds {
    "Mod+g" "submap:groups"
}

submaps {
    groups oneshot=#true {
        "n" "spawn-new-group"
        "l" "group-next"
        "h" "group-prev"
        "L" "group-to-plane-next"
        "t" "group-tag-toggle:work"
        "Escape" "submap-exit"
    }
}

Not yet: moving individual windows between groups, repositioning a group, and geometric cross-group focus are not implemented — groups move and tag as a unit, but you don't shuffle windows across group boundaries today.

Where to go next

These primitives are deliberately small so you can combine them. The workflow recipes show four ways to do exactly that, each with a copy-paste config.