space-tree is a tree-based workspace manager for Emacs. Workspaces are a battle-tested UX concept across operating systems, but in Emacs and most OSes alike, they're flat: you get a row, a grid, or a numbered list, but never a workspace inside a workspace. My requirements for a workspace manager were arbitrary-depth nesting, no naming tax, no mandatory persistence, no per-workspace buffer scoping, and a build that leans on Emacs's existing window-state primitives. The cognitive-psychology case for hierarchical organization turns out to be unusually robust: working-memory ceilings (Cowan 2001), expert chunking (Chase & Simon 1973), and direct gains in recall (Bower et al. 1969) all support the idea that a user-authored tree is easier to hold in mind than the same work flattened into a list. The feature matrix places space-tree as the only workspace manager in this survey with arbitrary-depth structure, optional naming, and a deliberately session-only memory model. The implementation is a small amount of Elisp built on window-state-get / window-state-put, with a nested hash table for the tree shape, a flat hash table for window-state snapshots, and a sparse hash table for optional names. Getting started is a use-package block plus a Super-key keymap.

When we use our computers, the vagaries of day-to-day activities fill our displays with an unbounded number of applications. The chaos here has led to an overwhelming number of 'workspace management' tools.

I see these tools pop up everywhere in my daily computer use. macOS and Windows have workspace management solutions out-of-the-box. Linux has the venerable i3 (and btw, Aerospace is a great alternative for macOS users).

We see these solutions pop up even at the application level. Web browsers have tab-groups, and some, like Vivaldi 💜, even have first-class workspaces. Most complex applications like browsers, IDEs, DAWs, and image-manipulation programs also offer workspace management at the 'frame' level, where each visible frame is typically scoped to one or a set of projects.

Even AR devices (I'm looking at you Apple Vision Pro), offer workspace management, albeit in a hilariously silly way: the advent of AR technology has enabled you to misplace applications all around your house. You might leave your Chef in the kitchen, your CouchDB on the sofa, your Brew in the beer fridge, or (worst of all) your git porcelain in the bathroom.

Of course, Emacs offers several workspace management tools. Besides the built-in tab-bar, there is a delicious cornucopia of 3rd party solutions (7 of which are discussed here). When you think about it, robust workspace management is more important in Emacs than anywhere else, especially for those of us who try to stuff the kitchen sink in there. The more concerns being handled by Emacs, the greater the burden on organizing and navigating those concerns. But most of Emacs's native and 3rd party solutions lack the ability to organize workspaces hierarchically.

Although I'm typically against hierarchical organization, for workspaces management I think it makes perfect sense. After all, workspace management tools are providing some digital simile for how we might organize things in the physical realm.

Think about how you organize things in your dwelling: a house has rooms, rooms have shelves, shelves have drawers. If you've ever heard the name 'Marie Kondo', then you have likely embraced that drawers too can have dividers. These can be commandeered for smaller drawer-within-a-drawer spaces the moment your proliferation of joyful treasures warrants a subdivision.

Physical space, when we organize it well, is recursive or tree-like. Digital workspaces, somehow, almost never are, and that's why I created space-tree (see code on GitHub), the subject of this post.

The "workspace" is an old, battle-scarred UX concept. Whatever you call them (virtual desktops on Windows, Spaces on macOS, workspaces in i3, sway, and GNOME) every major OS has shipped and continues to ship some version of the idea.

When the screen real estate runs out, we don't grow the screen, we shard it into workspaces. You get tidy partitions of the layouts you'd like to keep around, and you can switch between them with a keybinding or gesture that (should) feel speed-of-thought and reflexive.

Workspaces work because they are simple. Complex work involves more state than a single screenful can hold. Consider what I'm working with right now as I add this to my blog:

• When I'm fixing a failing test in space-tree, I'd like the test runner visible, the test source visible, the implementation visible, and a place to read stack traces.
• When I'm writing this post, I'd like the org file and the rendered preview.

The workspace exists because human working memory cannot hold the inventory that human work demands, so we ask the computer to hold it for us.

i3 users will recognize a slightly more aggressive version of the idea. Workspaces in i3 don't just hold a frozen tableau of windows. Each one is addressable, meaning it has a stable identifier you can jump to directly. With one keystroke, you teleport to a labeled context (`mod+1` to "browser", `mod+2` to "editor", `mod+3` to "terminals"). In this way, the cognitive cost of task-switching is reduced to the pressing of a single key. Once that cost collapses, you start partitioning more aggressively, because the cost-benefit of giving a sub-task its own workspace flips in your favor.

But what every OS workspace manager has in common is that the partition space is flat. You get a row, or a grid, or a numbered list, but you don't get a workspace inside a workspace. If a sub-task spawns its own sub-sub-tasks (and complex work always does), you run out of luck.

Emacsapiens have implemented the workspace notion so many times that "yet another workspace manager" is a respected subgenre on the various emacs wikis, threads, and servers. I almost called this package YAWM, but space-tree sounded way cooler 😉.

Each workspace management package in Emacs solves a slightly different facet of the same underlying problem, and each one implements its author's particular taste and workflow. The pile is large, and so a survey is in order before I justify adding to it.

• tab-bar-mode — Built into Emacs since version 27. A flat row of tabs across the top of the frame, where each tab holds a window configuration. Tab-switching is keyed by index or name. Persistence comes via desktop-save-mode.
• eyebrowse — A flat, numbered list of window configurations, frame-scoped, intentionally lightweight. This in my opinion is the granddaddy of the "virtual desktops in Emacs" idea, and was my daily driver for years until I built space-tree.
• perspective.el — Buffer scoping by named workspace. Each perspective restricts the buffer list to a subset, so switch-to-buffer only sees what's "in" the active perspective. Optional persistence across sessions.
• persp-mode — Independent fork with overlapping goals: buffer scoping plus window configurations, with per-frame perspectives and richer persistence.
• activities.el — alphapapa's modern take. An "activity" bundles frames, tabs, windows, and buffers, with snapshots saved as bookmarks (so you get cross-session persistence).
• burly — Also alphapapa's. Treats window/frame/tab layouts as bookmarks, leveraging the built-in bookmark machinery for restoration. More of a primitive than a workspace manager per se — activities builds on top of it.
• beframe — Protesilaos's per-frame buffer-list scoping. Each frame sees only the buffers opened from it.
• workgroups2 — A long-running spiritual successor to elscreen, with named saveable workgroups.

These are well-built tools, each by an author whose taste I respect, and each solving a real problem. I like and have used all of them, and if you're sick like me, I recommend you try them all too 🤪.

None of them, however, after a fair amount of usage, was quite right for me. I'm a little precious, like Goldilocks, when it comes to this sort of thing, so I decided to clearly lay out my minimum viable needs before whipping up my own porridge.

When I sat down to figure out why none of the above stuck, I realized I had a handful of stubborn requirements.

When developing space-tree, I was worried that the "tree" might just be a programmer's reflex. Everything looks like a tree once you've spent enough time staring at file systems, abstract syntax trees, and org-mode outlines. Maybe I was just imposing a preferred data structure on a solution that doesn't need it 🤔.

I did some research on this, and to my surprise, the cognitive psychology literature has been making the case for hierarchical organization of complex state since the 1950s, with unusually robust empirical support. Because the use-case of workspace switching needs to occur at the speed of thought, any reduction in the burden our naturally limited working memory is useful, and this burden is what the hierarchy alleviates.

I'll stop that hand-waving and get down to the evidence.

To help explain what space-tree offers amongst a large field of workspace management tools in Emacs, I've included a feature matrix. This is a crude summary of nuanced tools, and I encourage the curious reader to consult each project's README for a fairer picture.

You can see that space-tree is a different flavour from the same bag of sweets.

The cell that earns space-tree a special place in the matrix is the first one (Structure is arbitrary). Every other tool gives you a flat list with various toppings, but space-tree's distinguishing trait is that the workspace structure is a tree.

The implementation is small, by design. The whole thing, including docstrings, is ~680 lines of code at the time of this writing, and it could have been smaller if I'd used dash or ht.

At its core, space-tree is two simple ideas (plus a sparse third for names):

1. A tree of addresses. Each space is identified by a list of integers, read left to right as a path down the tree. (2 1 3) means "start at top-level space 2, descend to its 1st child, then to that child's 3rd child." The tree itself lives in a nested hash table whose values are hash tables, recursively. Creating a space writes a new key, and deleting a space removes a subtree.
2. A hash table from address to window state. When you switch to a space, the saved state is restored; when you leave one, the live state is snapshotted back. Branching creates a new address and seeds it with a fresh layout.

The native Emacs API is doing all the heavy lifting of storing and restoring the window layouts. The "window state" is what the built-in window-state-get returns, and what window-state-put accepts. These are the canonical Emacs primitives for serializing the arrangement of windows and their buffers in a frame, available since Emacs 24. space-tree adds no new representation of what a layout is. The only thing it adds is a shape for organizing many layouts at once.

To make the two ideas concrete: suppose a user has carved out the following spaces over the course of a session.

1
├── 1.1
│   └── 1.1.1
└── 1.2
2

The three hash tables of space-tree then look like this, assuming the user has named two of the spaces:

;; space-tree-tree              — the *shape*, as a nested hash table.
;; Keys are integer space numbers; values are child hash tables.
{
  1 → {
        1 → { 1 → {} },
        2 → {}
      },
  2 → {}
}

;; space-tree-address-wconf-tbl — the *snapshots*, as a flat hash table.
;; Keys are address lists; values are what `window-state-get' returns.
{
  (1)     → #<window-state ...>,
  (1 1)   → #<window-state ...>,
  (1 1 1) → #<window-state ...>,
  (1 2)   → #<window-state ...>,
  (2)     → #<window-state ...>
}

;; space-tree-space-name-tbl    — the *names*, as a flat hash table.
;; Keys are address lists; values are user-supplied display strings.
;; Sparse: only the spaces the user has explicitly named appear here.
{
  (1)   → "main",
  (1 1) → "investigation"
}

The first table encodes where the spaces sit, the second what each space contains, and the third which of them have been a named.

Switching to a space simply looks up its address in the second table and passes the result to window-state-put. Creating a child is simply walking the first table to the parent, adding a new key, and rendering a 'blank' (scratch buffer only) workspace. Deleting a space drops its structural entry. The names table is sparse (and rarely used ib my experience). Unnamed addresses simply don't appear in it, and the modeline falls back to the numeric label.

Strictly speaking, the structural table is redundant because each address is itself a root-to-node path, and the keys of the second table already encode the tree. It's there as an index for constant-time sibling enumeration. Honestly though, at realistic scale, it is a fair objection that this optimization doesn't matter. I'm just hash-table crazy 😝.

The total inventory of state:

• one hash table for the structural tree
• one hash table mapping address to window-state-get output
• one hash table mapping address to user-chosen name (optional, sparse)
• a list of recently visited addresses, for "last space" toggling
• one variable holding the current address

space-tree manages window configurations only. It does not scope your buffer list, restore frames across sessions, integrate with desktop.el, or coordinate with project.el.

This is deliberate. The packages I cited earlier solved a problem I didn't have (buffer scoping, persistence) by also solving the one I did (window layouts), and the bundling made it hard to mix-and-match. space-tree's restraint is its compatibility: it does the one thing I wanted, and it stays out of the way of anything else I'd like to compose with.

space-tree lives on GitHub. The README has the full command reference; here is a worked example of the install plus a full keymap with general.el that mirrors what I run in my own config.

(use-package space-tree
  :ensure (:host github :repo "chiply/space-tree")
  :config
  (space-tree-init)

  ;; Top-level spaces with Super key + number
  (general-define-key
   "s-1" #'space-tree-to-1
   "s-2" #'space-tree-to-2
   "s-3" #'space-tree-to-3
   "s-4" #'space-tree-to-4
   "s-5" #'space-tree-to-5
   "s-6" #'space-tree-to-6
   "s-7" #'space-tree-to-7
   "s-8" #'space-tree-to-8
   "s-9" #'space-tree-to-9

   ;; Second level (within current top-level space)
   "s-a" #'space-tree-sub-1
   "s-s" #'space-tree-sub-2
   "s-d" #'space-tree-sub-3
   "s-f" #'space-tree-sub-4
   "s-g" #'space-tree-sub-5

   ;; Third level (within current second-level space)
   "s-A" #'space-tree-sub-sub-1
   "s-S" #'space-tree-sub-sub-2
   "s-D" #'space-tree-sub-sub-3
   "s-F" #'space-tree-sub-sub-4
   "s-G" #'space-tree-sub-sub-5

   ;; Navigation
   "M-S-<tab>"   #'space-tree-switch-space-by-name
   "M-<tab>"     #'space-tree-go-to-last-space
   "C-M-<tab>"   #'space-tree-go-right
   "C-M-S-<tab>" #'space-tree-go-left

   ;; Delete current space (the command defaults to the current address)
   "s-_" #'space-tree-delete-space)

  ;; Evil/vim-style bindings
  (general-define-key
   :states '(normal visual)
   :keymaps 'override
   "gt" #'space-tree-switch-current-level
   "gT" #'space-tree-switch-space-by-digit-arg
   "g+" #'space-tree-create-space-top-level
   "gn" #'space-tree-create-space-current-level))

Drop the Evil block if you don't use Evil, and swap the Super-key prefix for whatever modifier your OS doesn't already consume (Hyper, Meta-Super, or just plain Meta with a different chord).

If you try it and something is broken, open an issue. If something is missing, open one with a feature request, or open a PR.

To the authors of the packages I surveyed: thank you. I learned something from each of yours before I built mine, and the fact that there is a respected subgenre of workspace managers in Emacs is, frankly, one of the things I love about this universe.