{"id":16313001,"url":"https://github.com/lthms/spatial-shell","last_synced_at":"2025-04-30T05:07:47.844Z","repository":{"id":127672191,"uuid":"527189827","full_name":"lthms/spatial-shell","owner":"lthms","description":"Implementing a spatial model inspired by Material Shell, for i3 and sway.","archived":false,"fork":false,"pushed_at":"2024-05-25T20:53:39.000Z","size":218,"stargazers_count":100,"open_issues_count":7,"forks_count":1,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-30T05:07:41.561Z","etag":null,"topics":["i3wm","material-shell","swaywm","tiling-window"],"latest_commit_sha":null,"homepage":"https://spatial-shell.app","language":"OCaml","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lthms.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-21T11:44:02.000Z","updated_at":"2025-04-22T22:38:41.000Z","dependencies_parsed_at":"2024-01-25T00:26:36.229Z","dependency_job_id":"e72c6d45-6b52-4585-ae06-67dcf550f5cf","html_url":"https://github.com/lthms/spatial-shell","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lthms%2Fspatial-shell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lthms%2Fspatial-shell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lthms%2Fspatial-shell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lthms%2Fspatial-shell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lthms","download_url":"https://codeload.github.com/lthms/spatial-shell/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251644842,"owners_count":21620634,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["i3wm","material-shell","swaywm","tiling-window"],"created_at":"2024-10-10T21:49:38.312Z","updated_at":"2025-04-30T05:07:47.825Z","avatar_url":"https://github.com/lthms.png","language":"OCaml","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spatial Shell\n\nSpatial Shell is a daemon implementing a spatial model inspired by [Material\nShell][material-shell], for [i3][i3] and [sway][sway]. More precisely, it\norganizes your windows within a grid whose rows are the workspaces of your\nfavorite WM.\n\nhttps://github.com/lthms/spatial-shell/assets/1141231/2e5a77d0-c1f1-4cba-a9a1-6604de13bbfe\n\nIn a nutshell, Spatial Shell allows you to:\n\n- Move the focus within the grid: on the left or on the right within the current\n  workspace, or on focused window of the upper or lower workspace. In the\n  former case, the current workspace does not change, while in the latter it\n  does.\n- Move the focused window within the grid: to the left or to the right within\n  the current workspace, or to the upper or lower workspace. In the former case,\n  the focused windows is swapped with its neighbor, while in the former it is\n  inserted at the right of the previously focused window within this row.\n- Configure how many windows are displayed at most within a given workspace\n  (for when the workspace uses the _column_ layout).\n- Toggle between the *Column* and _maximize_ layout for the current workspace\n  (see the *LAYOUT* section)\n\n## Installation\n\n### Building from Source\n\nYou will need `opam`.\n\nIf dynamically linked binaries are fine for your use case, then\nbuilding and installing Spatial Shell is as simple as the following.\n\n```bash\n# install dependencies\nmake build-deps\n# might be unnecessary depending on your setup. If you are not familiar with\n# OCaml and Opam, you probably need it.\neval $(opam env)\n# build\nmake\n# install spatial\nmake install\n```\n\n\u003e [!IMPORTANT]\n\u003e By default, `make install` installs the files in `$HOME/.local`. As a\n\u003e consequence, Spatial Shell binaries might not be available in your `PATH` out\n\u003e of the box, especially if starting your graphic session from a display\n\u003e manager. A good alternative is to install in `/usr/local`.\n\u003e\n\u003e ```bash\n\u003e DESTDIR=/usr/local make install\n\u003e ```\n\u003e\n\u003e You will probably need to run this command as `root`.\n\nIf you want to hack Spatial Shell, you can install common development\ndependencies with `make build-dev-deps`.\n\n### Building Static Binaries from Source\n\nAlternatively, you might want to build statically linked binaries for Spatial\nShell.\n\n```bash\n# If you have already created a local opam switch for Spatial Shell, remove it.\nopam switch remove .\n# You need a particular version of the OCaml compiler with no dependencies to\n# zstd (unused by Spatial Shell) and using muslc instead of glibc.\nOCAML_COMPILER=ocaml-option-static,ocaml-option-no-compression,ocaml.5.1.1 make build-deps\n# You have to use the `static` profile to build.\nBUILD_PROFILE=static make\n# You can use DESTDIR to choose where the binaries and manpages are installed.\n# See the note in the previous section.\nmake install\n```\n\n### Archlinux User Repository\n\nSpatial Shell has been packages for Archlinux (see the [AUR\npackage][aur]).\n\nFor instance, if you have [Yay][yay] available, you can install Spatial Shell\nwith the following command.\n\n```\nyay -S spatial-shell\n```\n\n### Official Binary Builds\n\nStarting with Spatial Shell 5th release, binary builds are attached to GitHub\nreleases for Linux (x86_64).\n\nSignatures are provided as well. The maintainer public key is\n[`320E11CB5316864648593D5E14CD43A3866E4C18`][pubkey].\n\n## Getting Started\n\nIn addition to the `spatial`, `spatialmsg` and `spatialblock` executables, this\ncommand installs several man pages: [`spatial(1)`][spatial.1],\n[`spatialmsg(1)`][spatialmsg.1], [`spatialblock(1)`][spatialblock.1],\n[`spatial(5)`][spatial.5], and [`spatial-ipc(7)`][spatial-ipc.7].\n\nSpatial Shell is primilarly documented via these manpages.\n\n### Configuring Your Favorite WM\n\nAt its core, Spatial Shell consists in a daemon (`spatial`) and a client\n(`spatialmsg`) communicating with a IPC protocol. The most straightforward way\nto run Spatial Shell daemon is via your favorite WM configuration file.\n\n```\n# Assuming `spatial` is available from $PATH\nexec spatial\n```\n\nOnce `spatial` is running, you can assign bindings to interact with it using\n`spatialmsg` as part of the configuration of your favorite WM.\n\n```\n# Assuming `spatialmsg` is available from $PATH\nbindsym $mod+h exec $spatialmsg \"focus left\"\nbindsym $mod+l exec $spatialmsg \"focus right\"\nbindsym $mod+k exec $spatialmsg \"focus up\"\nbindsym $mod+j exec $spatialmsg \"focus down\"\n```\n\nFor more information about the commands (including their exact syntax) which\ncan be sent to `spatial` via `spatialmsg`, see [`spatial(5)`][spatial.5]. \n\nThis repositor also includes a [minimal configuration example][min-config] that\nyou can use to quickly setup Spatial Shell.\n\n### Configuring Spatial Shell\n\nSpatial Shell searches for a config file in `$XDG_CONFIG_HOME/spatial/config`.\nIf `$XDG_CONFIG_HOME` is unset, it defaults to `$HOME/.config`.\n\nThe config file of Spatial Shell is a list of commands (one per line).\nAdditionally, a line starting with a `#` is ignored (but inline comments are\nnot supported, that is, it is not possible to add a comment at the end of a\nvalid command).\n\nSee [`spatial(5)`][spatial.5] for information about supported commands.\n\n### Configuring Your Favorite Status Bar\n\nSpatial Shell is a lot more enjoyable to use with some visual aids to help you\nvisualize the state of the grid. To that end, spatial can be configured to send\na signal (`SIGMIN+8`) to a status bar everytime the configuration of the grid\nchanges (that is when the focus or the order of the windows changes).\n\nspatial uses `pkill` to send the signal, and does so only when it has been\nprovided the name of the status bar program with the `status_bar_name` command.\nFor instance, assuming you are using [Waybar][waybar], add this line to your\nSpatial Shell config file.\n\n```\nstatus_bar_name \"waybar\"\n```\n\nThis repository includes examples of configuration for several status bar in\nthe [`contrib/` directory][contrib-dir]. These examples use `spatialblock`, a utility program\nconnecting directly to spatial socket (instead of relying on `spatialmsg`) in\norder to reduce latency.\n\n## Community\n\nIf you want to help build a nice community of hackers working on and users\nenjoying Spatial Shell, you can use one of these mediums.\n\n- [`r/spatialshell`][reddit] on Reddit\n- [#spatial-shell][irc] on [Libera.Chat][libera]\n\n## Acknowledgement\n\nSpatial Shell could not have been possible without sway, which remains a\nreference and a significant source of inspiration for the software architecture\nof this project, including for the wording of several man pages.\n\n[material-shell]: https://material-shell.com/\n[i3]: https://i3wm.org/\n[sway]: https://swaywm.org/\n[spatial.1]: https://spatial-shell.app/spatial.1.html\n[spatialmsg.1]: https://spatial-shell.app/spatialmsg.1.html\n[spatialblock.1]: https://spatial-shell.app/spatialblock.1.html\n[spatial.5]: https://spatial-shell.app/spatial.5.html\n[spatial-ipc.7]: https://spatial-shell.app/spatial-ipc.7.html\n[aur]: https://aur.archlinux.org/packages/spatial-shell\n[yay]: https://github.com/Jguer/yay\n[min-config]: ./contrib/sway/spatial.conf\n[waybar]: https://github.com/Alexays/Waybar\n[contrib-dir]: ./contrib/\n[pubkey]: https://soap.coffee/~lthms/files/lthms@soap.coffee.pub\n[reddit]: https://www.reddit.com/r/spatialshell/\n[irc]: irc://libera.chat/#spatial-shell\n[libera]: https://libera.chat/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flthms%2Fspatial-shell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flthms%2Fspatial-shell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flthms%2Fspatial-shell/lists"}