komorebi/docs/macos/README.md

# komorebi for Mac

Tiling Window Management for macOS.

<p>
  <a href="https://techforpalestine.org/learn-more">
    <img alt="Tech for Palestine" src="https://badge.techforpalestine.org/default">
  </a>

[//]: # '  <img alt="GitHub Workflow Status" src="https://img.shields.io/github/actions/workflow/status/LGUG2Z/komorebi-for-mac/.github/workflows/windows.yaml">'
[//]: # '  <img alt="GitHub all releases" src="https://img.shields.io/github/downloads/LGUG2Z/komorebi-for-mac/total">'
[//]: # '  <img alt="GitHub commits since latest release (by date) for a branch" src="https://img.shields.io/github/commits-since/LGUG2Z/komorebi-for-mac/latest">'

  <img alt="Active Individual Commercial Use Licenses" src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Flgug2z-ecstaticmagentacheetah.web.val.run&query=%24.&label=active%20individual%20commercial%20use%20licenses&cacheSeconds=3600&link=https%3A%2F%2Flgug2z.com%2Fsoftware%2Fkomorebi">

  <a href="https://discord.gg/mGkn66PHkx">
    <img alt="Discord" src="https://img.shields.io/discord/898554690126630914">
  </a>
  <a href="https://github.com/sponsors/LGUG2Z">
    <img alt="GitHub Sponsors" src="https://img.shields.io/github/sponsors/LGUG2Z">
  </a>
  <a href="https://ko-fi.com/lgug2z">
    <img alt="Ko-fi" src="https://img.shields.io/badge/kofi-tip-green">
  </a>
  <a href="https://notado.app/feeds/jado/software-development">
    <img alt="Notado Feed" src="https://img.shields.io/badge/Notado-Subscribe-informational">
  </a>
  <a href="https://www.youtube.com/channel/UCeai3-do-9O4MNy9_xjO6mg?sub_confirmation=1">
    <img alt="YouTube" src="https://img.shields.io/youtube/channel/subscribers/UCeai3-do-9O4MNy9_xjO6mg">
  </a>
</p>

<img width="2560" height="1080" alt="Screenshot 2025-10-06 at 3 55 50 PM" src="https://github.com/user-attachments/assets/93ee9c94-2df6-4211-9f8a-db34e3c0a604" />

## Overview

_komorebi for Mac_ is a tiling window manager that works as an extension to the
standard macOS desktop environment.

_komorebi for Mac_ aims to make _as few modifications as possible_ to the
operating system and desktop environment by default.

You can try the latest public release with `brew install
lgug2z/tap/komorebi-for-mac` or [build from
source](https://komorebi-starlight.lgug2z.workers.dev/guides/installation/#building-from-source),
and then follow the
[quickstart](https://komorebi-starlight.lgug2z.workers.dev/guides/quickstart/).

## Community

There is a [Discord server](https://discord.gg/mGkn66PHkx) available for
_komorebi_-related discussion, help, troubleshooting etc. If you have any
specific feature requests or bugs to report, please create an issue in this
repository.

There is
a [YouTube channel](https://www.youtube.com/channel/UCeai3-do-9O4MNy9_xjO6mg)
where I post _komorebi_ development videos, feature previews and release
overviews. Subscribing to the channel (which is monetized as part of the YouTube
Partner Program) and watching videos is a really simple and passive way to
contribute financially to the development and maintenance of _komorebi_.

There is an [Awesome List](https://github.com/LGUG2Z/awesome-komorebi) which
showcases the many awesome projects that exist in the _komorebi_ ecosystem.

## Licensing for Personal Use

`komorebi`
is [educational source software](https://lgug2z.com/articles/educational-source-software/).

`komorebi` is licensed under
the [Komorebi 2.0.0 license](https://github.com/LGUG2Z/komorebi-license), which
is a fork of
the [PolyForm Strict 1.0.0 license](https://polyformproject.org/licenses/strict/1.0.0).
On a high level this means that you are free to do whatever you want with
`komorebi` for personal use other than redistribution, or distribution of new
works (i.e. hard-forks) based on the software.

Anyone is free to make their own fork of `komorebi` with changes intended either
for personal use or for integration back upstream via pull requests.

The [Komorebi 2.0.0 License](https://github.com/LGUG2Z/komorebi-license) does
not permit any kind of commercial use ( i.e. using `komorebi` at work).

## Sponsorship for Personal Use

_komorebi for Mac_ is a free and educational source project, and one that
encourages you to make charitable donations if you find the software to be
useful and have the financial means.

I encourage you to make a charitable donation to
the [Palestine Children's Relief Fund](https://pcrf1.app.neoncrm.com/forms/gaza-recovery)
or to contribute to a [Gaza Funds campaign](https://gazafunds.com) before you
consider sponsoring me on GitHub.

[GitHub Sponsors is enabled for this project](https://github.com/sponsors/LGUG2Z).
Sponsors can claim custom roles on the Discord server, get shout outs at the end
of _komorebi_-related videos on YouTube, gain the ability to submit feature
requests on the issue tracker, and receive releases of komorebi with "easter
eggs" on physical media.

Feature requests for all platforms (Windows, Linux and macOS) are accepted from
current [GitHub sponsors](https://github.com/sponsors/LGUG2Z) on the $5/month tier
and above, people with a valid [individual commercial use
license](https://lgug2z.com/software/komorebi), and approved contributors. Issues
titled `[FEAT]: ` opened by anyone else are closed automatically. Bug reports are
open to everyone.

If you would like to tip or sponsor the project but are unable to use GitHub
Sponsors, you may also sponsor through [Ko-fi](https://ko-fi.com/lgug2z), or
make an anonymous Bitcoin donation to
`bc1qv73wzspc77k46uty4vp85x8sdp24mphvm58f6q`.

## Licensing for Commercial Use

A dedicated Individual Commercial Use License is available for those who want to
use `komorebi` at work.

The Individual Commerical Use License adds “Commercial Use” as a “Permitted Use”
for the licensed individual only, for the duration of a valid paid license
subscription only. All provisions and restrictions enumerated in the [Komorebi
License](https://github.com/LGUG2Z/komorebi-license) continue to apply.

More information, pricing and purchase links for Individual Commercial Use
Licenses [can be found here](https://lgug2z.com/software/komorebi).

# Contribution Guidelines

_komorebi for Mac_ is currently accepting minimally invasive bug fixes.
Proposals for any other kind of contributions can be discussed with me on
Discord.

If you would like to contribute to `komorebi` please take the time to carefully
read the guidelines below.

Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for more information about how
code contributions to `komorebi` are licensed.

## Commit hygiene

- Flatten all `use` statements
- Run `cargo +stable clippy` and ensure that all lints and suggestions have been
  addressed before committing
- Run `cargo +nightly fmt --all` to ensure consistent formatting before
  committing
- Use `git cz` with
  the [Commitizen CLI](https://github.com/commitizen/cz-cli#conventional-commit-messages-as-a-global-utility)
  to prepare commit messages
- Provide **at least** one short sentence or paragraph in your commit message
  body to describe your thought process for
  the changes being committed

## PRs should contain only a single feature or bug fix

It is very difficult to review pull requests which touch multiple unrelated
features and parts of the codebase.

Please do not submit pull requests like this; you will be asked to separate them
into smaller PRs that deal only with one feature or bug fix at a time.

If you are working on multiple features and bug fixes, I suggest that you cut a
branch called `local-trunk` from `master` which you keep up to date, and rebase
the various independent branches you are working on onto that branch if you want
to test them together or create a build with everything integrated.

## Refactors to the codebase must have prior approval

`komorebi` is a mature codebase with an internal consistency and structure that
has developed organically over close to half a decade.

There are [countless hours of live coding videos](https://youtube.com/@LGUG2Z)
demonstrating work on this project and showing new contributors how to do
everything from basic tasks like implementing new `komorebic` commands to
distinguishing monitors by manufacturer hardware identifiers and video card
ports.

Refactors to the structure of the codebase are not taken lightly and require
prior discussion and approval.

Please do not start refactoring the codebase with the expectation of having your
changes integrated until you receive an explicit approval or a request to do so.

Similarly, when implementing features and bug fixes, please stick to the
structure of the codebase as much as possible and do not take this as an
opportunity to do some "refactoring along the way".

It is extremely difficult to review PRs for features and bug fixes if they are
lost in sweeping changes to the structure of the codebase.

## Breaking changes to user-facing interfaces are unacceptable

This includes but is not limited to:

- All `komorebic` commands
- The `komorebi.json` schema
- The [
  `komorebi-application-specific-configuration`](https://github.com/LGUG2Z/komorebi-application-specific-configuration)
  schema

No user should ever find that their configuration file has stopped working after
upgrading to a new version of `komorebi`.

More often than not there are ways to reformulate changes that may initially
seem like they require breaking user-facing interfaces into additive changes.

For some inspiration please take a look
at [this commit](https://github.com/LGUG2Z/komorebi/commit/e7d928a065eb63bb4ea1fb864c69c1cae8cc763b)
which added the ability for users to specify colours in `komorebi.json` in Hex
format alongside RGB.

There is also a process in place for graceful, non-breaking, deprecation of
configuration options that are no longer required.

# Logs and Debugging

Logs from `komorebi` will be appended to
`$HOME/Library/Application Support/komorebi/komorebi.log.$timestamp`.

Whenever running the `komorebic stop` command or sending a Ctrl-C signal to
`komorebi` directly, the `komorebi` process ensures that all hidden windows are
restored before termination.

## Panics and Deadlocks

If `komorebi` ever stops responding, it is most likely either due to either a
panic or a deadlock. In the case of a panic, this will be reported in the log.
In the case of a deadlock, there will not be any errors in the log, but the
process and the log will appear frozen.

If you believe you have encountered a deadlock, you can compile `komorebi` with
`--features deadlock_detection` and try reproducing the deadlock again. This
will check for deadlocks every 5 seconds in the background, and if a deadlock is
found, information about it will appear in the log which can be shared when
opening an issue.

# Window Manager State and Integrations

The current state of the window manager can be queried using the
`komorebic state` command, which returns a JSON representation of the `State`
struct.

This may also be polled to build further integrations and widgets on top of.

# Window Manager Event Subscriptions

## Unix Domain Sockets

It is possible to subscribe to notifications of every `WindowManagerEvent` and
`SocketMessage` handled by `komorebi` using Unix Domain Sockets.

UDS are also the only mode of communication between `komorebi` and `komorebic`.

First, your application must create a socket in `$HOME/Library/Application
Support/komorebi`. Once the socket has been created, run the following command:

```bash
komorebic subscribe-socket <your socket name>
```

If the socket exists, komorebi will start pushing JSON data of successfully
handled events and messages as in the example above in the Named Pipes section.

## Rust Client

It is possible to use the `komorebi-client` crate to subscribe to notifications
of every `WindowManagerEvent` and `SocketMessage` handled by `komorebi` in a
Rust codebase.

Below is a simple example of how to use `komorebi-client` in a basic Rust application.

```rust
// komorebi-client = { git = "https://github.com/LGUG2Z/komorebi-for-mac" }

use anyhow::Result;
use komorebi_client::Notification;
use komorebi_client::NotificationEvent;
use komorebi_client::UnixListener;
use komorebi_client::WindowManagerEvent;
use std::io::BufRead;
use std::io::BufReader;
use std::io::Read;

pub fn main() -> anyhow::Result<()> {
  let socket = komorebi_client::subscribe(NAME)?;

  for incoming in socket.incoming() {
    match incoming {
      Ok(data) => {
        let reader = BufReader::new(data.try_clone()?);

        for line in reader.lines().flatten() {
          let notification: Notification = match serde_json::from_str(&line) {
            Ok(notification) => notification,
            Err(error) => {
              log::debug!("discarding malformed komorebi notification: {error}");
              continue;
            }
          };

          // match and filter on desired notifications
        }
      }
      Err(error) => {
        log::debug!("{error}");
      }
    }
  }

}
```

## Subscription Event Notification Schema

A [JSON Schema](https://json-schema.org/) of the event notifications emitted to
subscribers can be generated with the `komorebic notification-schema` command.

## Socket Message Schema

A [JSON Schema](https://json-schema.org/) of socket messages used to send
instructions to `komorebi` can be generated with the `komorebic socket-schema`
command.