Files
komorebi/docs/macos/installation.md
T
LGUG2Z 9a87be9165 docs(macos): remove the private repository paragraph, state the one policy
docs/macos/README.md: delete the paragraphs naming LGUG2Z/komorebi-for-mac as the
public release repository and KomoCorp/komorebi-for-mac as a private repository
for certain sponsor tiers with nightly releases (the private repository is retired
and nothing replaces it); add the one policy paragraph to its sponsorship section.
docs/macos/index.md: the same policy paragraph.
docs/macos/installation.md: OWNER markers only, on the Nix flake section that adds
the private repository as an input and on the nightly Homebrew line; text left
as it was because the replacement is the owner's decision.

Not verified beyond reading the diff.
2026-11-05 15:03:27 -08:00

144 lines
4.2 KiB
Markdown

# Getting started
`komorebi` is a tiling window manager for macOS that is comprised of two
main binaries, `komorebi`, which contains the window manager itself,
and `komorebic`, which is the main way to send commands to the tiling
window manager.
It is important to note that neither `komorebi` nor `komorebic` handle
key bindings, because `komorebi` is a tiling window manager and not a hotkey
daemon.
This getting started guide suggests the installation of
[`skhd`](https://github.com/koekeishiya/skhd) to allow you to bind `komorebic`
commands to hotkeys to allow you to communicate with the tiling window manager
using keyboard shortcuts.
## Installation
<!-- OWNER: does the `komorebi-for-mac-nightly` Homebrew package and "nightly builds" survive the consolidation (and from which repository)? Left unchanged. -->
Nightly builds are available to install
via [Homebrew](https://github.com/LGUG2Z/homebrew-tap), and you may also build
from source if you would prefer.
- [Homebrew](#homebrew)
- [Building from source](#building-from-source)
## System settings suggestions
Go to `System Settings -> Desktop & Dock -> Mission Control -> Displays have
separate Spaces` and disable this option if you are using more than one monitor.
`komorebi` is scoped to a single macOS space (the one that is active when the
process is started), which means that you can still use other Spaces as if
`komorebi` were not running at all. If you are using monitors with the above
option enabled, komorebi will only be listening to events from the Space on the
monitor which it was launched on.
Go to `System Settings -> Desktop & Dock -> Mission Control -> Group windows
by application` and disable this option if you like to use mission control.
## Homebrew
First add the `lgug2z/tap` Homebrew Tap
```shell
brew tap lgug2z/tap
```
Then install the `komorebi-for-mac-nightly` package
```shell
brew install lgug2z/tap/komorebi-for-mac-nightly
```
You may also optionally install the `skhd` package
```shell
brew install skhd
```
## Nix Flake
<!-- OWNER: this section tells users to add the private KomoCorp/komorebi-for-mac repository as a flake input with a GitHub token; that repository is retired. What is the public flake input for macOS (the root flake output names are not final)? Left unchanged until decided. -->
Ensure that your system Flake is configured to use your GitHub token so that you can add a private repository as an input
```nix
{
nix = {
settings = {
access-tokens = [
"github.com=YOUR ACCESS TOKEN"
];
};
};
}
```
Add the repository as an input
```nix
{
inputs.komorebi-for-mac.url = "github:KomoCorp/komorebi-for-mac";
}
```
Add the overlay to your system's nixpkgs configuration
```nix
{
pkgs = import nixpkgs {
inherit system;
overlays = [ komorebi-for-mac.overlays.default ];
# the rest of your pkgs configuration
};
}
```
Add `pkgs.komorebi-full` to `environment.systemPackages` (you may also add
`pkgs.komorebi`, `pkgs.komorebic` and `pkgs.komorebi-bar` individually)
```nix
{
environment.systemPackages = [
pkgs.komorebi-full
];
}
```
## Building from source
Make sure you have installed [`rustup`](https://rustup.rs), and a stable `rust`
compiler toolchain.
Clone the git repository, enter the directory, and build the following binaries:
```powershell
cargo +stable install --path komorebi-daemon --locked --target-dir ~/.cargo/bin
cargo +stable install --path komorebic --locked --target-dir ~/.cargo/bin
cargo +stable install --path komorebi-bar --locked --target-dir ~/.cargo/bin
```
If the binaries have been built and added to your `$PATH` correctly, you should
see some output when running `komorebi --help` and `komorebic --help`
Once komorebi is installed, proceed to get
the [example configurations](example-configurations.md).
## Uninstallation
Before uninstalling, first run `komorebic stop` to make sure that
the `komorebi` processes have been stopped.
Finally, you can run the following commands to clean up files created by the
`quickstart` command and any other runtime files:
```powershell
rm -rf ~/.cargo/bin/komorebi
rm -rf ~/.cargo/bin/komorebic
rm -rf ~/.cargo/bin/komorebi-bar
rm -rf ~/.config/komorebi
rm -rf "~/Library/Application Support/komorebi"
```