Spatial Shell

Spatial Shell is a daemon implementing a spatial model inspired by Material Shell, for i3 and sway. More precisely, it organizes your windows within a grid whose rows are the workspaces of your favorite WM.

demo.mp4

In a nutshell, Spatial Shell allows you to:

• Move the focus within the grid: on the left or on the right within the current workspace, or on focused window of the upper or lower workspace. In the former case, the current workspace does not change, while in the latter it does.
• Move the focused window within the grid: to the left or to the right within the current workspace, or to the upper or lower workspace. In the former case, the focused windows is swapped with its neighbor, while in the former it is inserted at the right of the previously focused window within this row.
• Configure how many windows are displayed at most within a given workspace (for when the workspace uses the column layout).
• Toggle between the Column and maximize layout for the current workspace (see the LAYOUT section)

Installation

Building from Source

You will need opam.

If dynamically linked binaries are fine for your use case, then building and installing Spatial Shell is as simple as the following.

# install dependencies
make build-deps
# might be unnecessary depending on your setup. If you are not familiar with
# OCaml and Opam, you probably need it.
eval $(opam env)
# build
make
# install spatial
make install

Important

By default, make install installs the files in $HOME/.local. As a consequence, Spatial Shell binaries might not be available in your PATH out of the box, especially if starting your graphic session from a display manager. A good alternative is to install in /usr/local.

DESTDIR=/usr/local make install

You will probably need to run this command as root.

If you want to hack Spatial Shell, you can install common development dependencies with make build-dev-deps.

Building Static Binaries from Source

Alternatively, you might want to build statically linked binaries for Spatial Shell.

# If you have already created a local opam switch for Spatial Shell, remove it.
opam switch remove .
# You need a particular version of the OCaml compiler with no dependencies to
# zstd (unused by Spatial Shell) and using muslc instead of glibc.
OCAML_COMPILER=ocaml-option-static,ocaml-option-no-compression,ocaml.5.1.1 make build-deps
# You have to use the `static` profile to build.
BUILD_PROFILE=static make
# You can use DESTDIR to choose where the binaries and manpages are installed.
# See the note in the previous section.
make install

Archlinux User Repository

Spatial Shell has been packages for Archlinux (see the AUR package).

For instance, if you have Yay available, you can install Spatial Shell with the following command.

yay -S spatial-shell

Official Binary Builds

Starting with Spatial Shell 5th release, binary builds are attached to GitHub releases for Linux (x86_64).

Signatures are provided as well. The maintainer public key is 320E11CB5316864648593D5E14CD43A3866E4C18.

Getting Started

In addition to the spatial, spatialmsg and spatialblock executables, this command installs several man pages: spatial(1), spatialmsg(1), spatialblock(1), spatial(5), and spatial-ipc(7).

Spatial Shell is primilarly documented via these manpages.

Configuring Your Favorite WM

At its core, Spatial Shell consists in a daemon (spatial) and a client (spatialmsg) communicating with a IPC protocol. The most straightforward way to run Spatial Shell daemon is via your favorite WM configuration file.

# Assuming `spatial` is available from $PATH
exec spatial

Once spatial is running, you can assign bindings to interact with it using spatialmsg as part of the configuration of your favorite WM.

# Assuming `spatialmsg` is available from $PATH
bindsym $mod+h exec $spatialmsg "focus left"
bindsym $mod+l exec $spatialmsg "focus right"
bindsym $mod+k exec $spatialmsg "focus up"
bindsym $mod+j exec $spatialmsg "focus down"

For more information about the commands (including their exact syntax) which can be sent to spatial via spatialmsg, see spatial(5).

This repositor also includes a minimal configuration example that you can use to quickly setup Spatial Shell.

Configuring Spatial Shell

Spatial Shell searches for a config file in $XDG_CONFIG_HOME/spatial/config. If $XDG_CONFIG_HOME is unset, it defaults to $HOME/.config.

The config file of Spatial Shell is a list of commands (one per line). Additionally, a line starting with a # is ignored (but inline comments are not supported, that is, it is not possible to add a comment at the end of a valid command).

See spatial(5) for information about supported commands.

Configuring Your Favorite Status Bar

Spatial Shell is a lot more enjoyable to use with some visual aids to help you visualize the state of the grid. To that end, spatial can be configured to send a signal (SIGMIN+8) to a status bar everytime the configuration of the grid changes (that is when the focus or the order of the windows changes).

spatial uses pkill to send the signal, and does so only when it has been provided the name of the status bar program with the status_bar_name command. For instance, assuming you are using Waybar, add this line to your Spatial Shell config file.

status_bar_name "waybar"

This repository includes examples of configuration for several status bar in the contrib/ directory. These examples use spatialblock, a utility program connecting directly to spatial socket (instead of relying on spatialmsg) in order to reduce latency.

Community

If you want to help build a nice community of hackers working on and users enjoying Spatial Shell, you can use one of these mediums.

• r/spatialshell on Reddit
• #spatial-shell on Libera.Chat

Acknowledgement

Spatial Shell could not have been possible without sway, which remains a reference and a significant source of inspiration for the software architecture of this project, including for the wording of several man pages.