{"id":44212073,"url":"https://github.com/lgug2z/komorebi-for-mac","last_synced_at":"2026-03-02T03:08:06.541Z","repository":{"id":335910480,"uuid":"1058319283","full_name":"LGUG2Z/komorebi-for-mac","owner":"LGUG2Z","description":"A tiling window manager for macOS 🍉 ","archived":false,"fork":false,"pushed_at":"2026-02-09T11:32:14.000Z","size":2123,"stargazers_count":76,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-10T02:47:20.981Z","etag":null,"topics":["komorebi","macos","rust","tiling-window-manager"],"latest_commit_sha":null,"homepage":"https://komorebi.lgug2z.com","language":"Rust","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LGUG2Z.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"LGUG2Z","ko_fi":"lgug2z"}},"created_at":"2025-09-16T23:53:54.000Z","updated_at":"2026-02-10T00:20:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/LGUG2Z/komorebi-for-mac","commit_stats":null,"previous_names":["lgug2z/komorebi-for-mac"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/LGUG2Z/komorebi-for-mac","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LGUG2Z%2Fkomorebi-for-mac","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LGUG2Z%2Fkomorebi-for-mac/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LGUG2Z%2Fkomorebi-for-mac/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LGUG2Z%2Fkomorebi-for-mac/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LGUG2Z","download_url":"https://codeload.github.com/LGUG2Z/komorebi-for-mac/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LGUG2Z%2Fkomorebi-for-mac/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29991312,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["komorebi","macos","rust","tiling-window-manager"],"created_at":"2026-02-10T00:37:53.682Z","updated_at":"2026-03-02T03:08:06.536Z","avatar_url":"https://github.com/LGUG2Z.png","language":"Rust","funding_links":["https://github.com/sponsors/LGUG2Z","https://ko-fi.com/lgug2z"],"categories":[],"sub_categories":[],"readme":"# komorebi for Mac\n\nTiling Window Management for macOS.\n\n\u003cp\u003e\n  \u003ca href=\"https://techforpalestine.org/learn-more\"\u003e\n    \u003cimg alt=\"Tech for Palestine\" src=\"https://badge.techforpalestine.org/default\"\u003e\n  \u003c/a\u003e\n\n[//]: # '  \u003cimg alt=\"GitHub Workflow Status\" src=\"https://img.shields.io/github/actions/workflow/status/LGUG2Z/komorebi-for-mac/.github/workflows/windows.yaml\"\u003e'\n[//]: # '  \u003cimg alt=\"GitHub all releases\" src=\"https://img.shields.io/github/downloads/LGUG2Z/komorebi-for-mac/total\"\u003e'\n[//]: # '  \u003cimg alt=\"GitHub commits since latest release (by date) for a branch\" src=\"https://img.shields.io/github/commits-since/LGUG2Z/komorebi-for-mac/latest\"\u003e'\n\n  \u003cimg alt=\"Active Individual Commercial Use Licenses\" src=\"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Flgug2z-ecstaticmagentacheetah.web.val.run\u0026query=%24.\u0026label=active%20individual%20commercial%20use%20licenses\u0026cacheSeconds=3600\u0026link=https%3A%2F%2Flgug2z.com%2Fsoftware%2Fkomorebi\"\u003e\n\n  \u003ca href=\"https://discord.gg/mGkn66PHkx\"\u003e\n    \u003cimg alt=\"Discord\" src=\"https://img.shields.io/discord/898554690126630914\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/sponsors/LGUG2Z\"\u003e\n    \u003cimg alt=\"GitHub Sponsors\" src=\"https://img.shields.io/github/sponsors/LGUG2Z\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://ko-fi.com/lgug2z\"\u003e\n    \u003cimg alt=\"Ko-fi\" src=\"https://img.shields.io/badge/kofi-tip-green\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://notado.app/feeds/jado/software-development\"\u003e\n    \u003cimg alt=\"Notado Feed\" src=\"https://img.shields.io/badge/Notado-Subscribe-informational\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.youtube.com/channel/UCeai3-do-9O4MNy9_xjO6mg?sub_confirmation=1\"\u003e\n    \u003cimg alt=\"YouTube\" src=\"https://img.shields.io/youtube/channel/subscribers/UCeai3-do-9O4MNy9_xjO6mg\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cimg 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\" /\u003e\n\n## Overview\n\n_komorebi for Mac_ is a tiling window manager that works as an extension to the\nstandard macOS desktop environment.\n\n_komorebi for Mac_ aims to make _as few modifications as possible_ to the\noperating system and desktop environment by default.\n\n[LGUG2Z/komorebi-for-mac](https://github.com/LGUG2Z/komorebi-for-mac) is the\npublic repository where versioned releases will be published.\n\n[KomoCorp/komorebi-for-mac](https://github.com/KomoCorp/komorebi-for-mac) is the\nprivate repository available to certain GitHub Sponsors tiers where ongoing\ndevelopment work happens and nightly releases are made available.\n\nYou can try the latest public release with `brew install\nlgug2z/tap/komorebi-for-mac` or [build from\nsource](https://komorebi-starlight.lgug2z.workers.dev/guides/installation/#building-from-source),\nand then follow the\n[quickstart](https://komorebi-starlight.lgug2z.workers.dev/guides/quickstart/).\n\n## Community\n\nThere is a [Discord server](https://discord.gg/mGkn66PHkx) available for\n_komorebi_-related discussion, help, troubleshooting etc. If you have any\nspecific feature requests or bugs to report, please create an issue in this\nrepository.\n\nThere is\na [YouTube channel](https://www.youtube.com/channel/UCeai3-do-9O4MNy9_xjO6mg)\nwhere I post _komorebi_ development videos, feature previews and release\noverviews. Subscribing to the channel (which is monetized as part of the YouTube\nPartner Program) and watching videos is a really simple and passive way to\ncontribute financially to the development and maintenance of _komorebi_.\n\nThere is an [Awesome List](https://github.com/LGUG2Z/awesome-komorebi) which\nshowcases the many awesome projects that exist in the _komorebi_ ecosystem.\n\n## Licensing for Personal Use\n\n`komorebi`\nis [educational source software](https://lgug2z.com/articles/educational-source-software/).\n\n`komorebi` is licensed under\nthe [Komorebi 2.0.0 license](https://github.com/LGUG2Z/komorebi-license), which\nis a fork of\nthe [PolyForm Strict 1.0.0 license](https://polyformproject.org/licenses/strict/1.0.0).\nOn a high level this means that you are free to do whatever you want with\n`komorebi` for personal use other than redistribution, or distribution of new\nworks (i.e. hard-forks) based on the software.\n\nAnyone is free to make their own fork of `komorebi` with changes intended either\nfor personal use or for integration back upstream via pull requests.\n\nThe [Komorebi 2.0.0 License](https://github.com/LGUG2Z/komorebi-license) does\nnot permit any kind of commercial use ( i.e. using `komorebi` at work).\n\n## Sponsorship for Personal Use\n\n_komorebi for Mac_ is a free and educational source project, and one that\nencourages you to make charitable donations if you find the software to be\nuseful and have the financial means.\n\nI encourage you to make a charitable donation to\nthe [Palestine Children's Relief Fund](https://pcrf1.app.neoncrm.com/forms/gaza-recovery)\nor to contribute to a [Gaza Funds campaign](https://gazafunds.com) before you\nconsider sponsoring me on GitHub.\n\n[GitHub Sponsors is enabled for this project](https://github.com/sponsors/LGUG2Z).\nSponsors can claim custom roles on the Discord server, get shout outs at the end\nof _komorebi_-related videos on YouTube, gain the ability to submit feature\nrequests on the issue tracker, and receive releases of komorebi with \"easter\neggs\" on physical media.\n\nIf you would like to tip or sponsor the project but are unable to use GitHub\nSponsors, you may also sponsor through [Ko-fi](https://ko-fi.com/lgug2z), or\nmake an anonymous Bitcoin donation to\n`bc1qv73wzspc77k46uty4vp85x8sdp24mphvm58f6q`.\n\n## Licensing for Commercial Use\n\nA dedicated Individual Commercial Use License is available for those who want to\nuse `komorebi` at work.\n\nThe Individual Commerical Use License adds “Commercial Use” as a “Permitted Use”\nfor the licensed individual only, for the duration of a valid paid license\nsubscription only. All provisions and restrictions enumerated in the [Komorebi\nLicense](https://github.com/LGUG2Z/komorebi-license) continue to apply.\n\nMore information, pricing and purchase links for Individual Commercial Use\nLicenses [can be found here](https://lgug2z.com/software/komorebi).\n\n# Contribution Guidelines\n\n_komorebi for Mac_ is currently accepting minimally invasive bug fixes.\nProposals for any other kind of contributions can be discussed with me on\nDiscord.\n\nIf you would like to contribute to `komorebi` please take the time to carefully\nread the guidelines below.\n\nPlease see [CONTRIBUTING.md](./CONTRIBUTING.md) for more information about how\ncode contributions to `komorebi` are licensed.\n\n## Commit hygiene\n\n- Flatten all `use` statements\n- Run `cargo +stable clippy` and ensure that all lints and suggestions have been\n  addressed before committing\n- Run `cargo +nightly fmt --all` to ensure consistent formatting before\n  committing\n- Use `git cz` with\n  the [Commitizen CLI](https://github.com/commitizen/cz-cli#conventional-commit-messages-as-a-global-utility)\n  to prepare commit messages\n- Provide **at least** one short sentence or paragraph in your commit message\n  body to describe your thought process for\n  the changes being committed\n\n## PRs should contain only a single feature or bug fix\n\nIt is very difficult to review pull requests which touch multiple unrelated\nfeatures and parts of the codebase.\n\nPlease do not submit pull requests like this; you will be asked to separate them\ninto smaller PRs that deal only with one feature or bug fix at a time.\n\nIf you are working on multiple features and bug fixes, I suggest that you cut a\nbranch called `local-trunk` from `master` which you keep up to date, and rebase\nthe various independent branches you are working on onto that branch if you want\nto test them together or create a build with everything integrated.\n\n## Refactors to the codebase must have prior approval\n\n`komorebi` is a mature codebase with an internal consistency and structure that\nhas developed organically over close to half a decade.\n\nThere are [countless hours of live coding videos](https://youtube.com/@LGUG2Z)\ndemonstrating work on this project and showing new contributors how to do\neverything from basic tasks like implementing new `komorebic` commands to\ndistinguishing monitors by manufacturer hardware identifiers and video card\nports.\n\nRefactors to the structure of the codebase are not taken lightly and require\nprior discussion and approval.\n\nPlease do not start refactoring the codebase with the expectation of having your\nchanges integrated until you receive an explicit approval or a request to do so.\n\nSimilarly, when implementing features and bug fixes, please stick to the\nstructure of the codebase as much as possible and do not take this as an\nopportunity to do some \"refactoring along the way\".\n\nIt is extremely difficult to review PRs for features and bug fixes if they are\nlost in sweeping changes to the structure of the codebase.\n\n## Breaking changes to user-facing interfaces are unacceptable\n\nThis includes but is not limited to:\n\n- All `komorebic` commands\n- The `komorebi.json` schema\n- The [\n  `komorebi-application-specific-configuration`](https://github.com/LGUG2Z/komorebi-application-specific-configuration)\n  schema\n\nNo user should ever find that their configuration file has stopped working after\nupgrading to a new version of `komorebi`.\n\nMore often than not there are ways to reformulate changes that may initially\nseem like they require breaking user-facing interfaces into additive changes.\n\nFor some inspiration please take a look\nat [this commit](https://github.com/LGUG2Z/komorebi/commit/e7d928a065eb63bb4ea1fb864c69c1cae8cc763b)\nwhich added the ability for users to specify colours in `komorebi.json` in Hex\nformat alongside RGB.\n\nThere is also a process in place for graceful, non-breaking, deprecation of\nconfiguration options that are no longer required.\n\n# Logs and Debugging\n\nLogs from `komorebi` will be appended to\n`$HOME/Library/Application Support/komorebi/komorebi.log.$timestamp`.\n\nWhenever running the `komorebic stop` command or sending a Ctrl-C signal to\n`komorebi` directly, the `komorebi` process ensures that all hidden windows are\nrestored before termination.\n\n## Panics and Deadlocks\n\nIf `komorebi` ever stops responding, it is most likely either due to either a\npanic or a deadlock. In the case of a panic, this will be reported in the log.\nIn the case of a deadlock, there will not be any errors in the log, but the\nprocess and the log will appear frozen.\n\nIf you believe you have encountered a deadlock, you can compile `komorebi` with\n`--features deadlock_detection` and try reproducing the deadlock again. This\nwill check for deadlocks every 5 seconds in the background, and if a deadlock is\nfound, information about it will appear in the log which can be shared when\nopening an issue.\n\n# Window Manager State and Integrations\n\nThe current state of the window manager can be queried using the\n`komorebic state` command, which returns a JSON representation of the `State`\nstruct.\n\nThis may also be polled to build further integrations and widgets on top of.\n\n# Window Manager Event Subscriptions\n\n## Unix Domain Sockets\n\nIt is possible to subscribe to notifications of every `WindowManagerEvent` and\n`SocketMessage` handled by `komorebi` using Unix Domain Sockets.\n\nUDS are also the only mode of communication between `komorebi` and `komorebic`.\n\nFirst, your application must create a socket in `$HOME/Library/Application\nSupport/komorebi`. Once the socket has been created, run the following command:\n\n```bash\nkomorebic subscribe-socket \u003cyour socket name\u003e\n```\n\nIf the socket exists, komorebi will start pushing JSON data of successfully\nhandled events and messages as in the example above in the Named Pipes section.\n\n## Rust Client\n\nIt is possible to use the `komorebi-client` crate to subscribe to notifications\nof every `WindowManagerEvent` and `SocketMessage` handled by `komorebi` in a\nRust codebase.\n\nBelow is a simple example of how to use `komorebi-client` in a basic Rust application.\n\n```rust\n// komorebi-client = { git = \"https://github.com/LGUG2Z/komorebi-for-mac\" }\n\nuse anyhow::Result;\nuse komorebi_client::Notification;\nuse komorebi_client::NotificationEvent;\nuse komorebi_client::UnixListener;\nuse komorebi_client::WindowManagerEvent;\nuse std::io::BufRead;\nuse std::io::BufReader;\nuse std::io::Read;\n\npub fn main() -\u003e anyhow::Result\u003c()\u003e {\n  let socket = komorebi_client::subscribe(NAME)?;\n\n  for incoming in socket.incoming() {\n    match incoming {\n      Ok(data) =\u003e {\n        let reader = BufReader::new(data.try_clone()?);\n\n        for line in reader.lines().flatten() {\n          let notification: Notification = match serde_json::from_str(\u0026line) {\n            Ok(notification) =\u003e notification,\n            Err(error) =\u003e {\n              log::debug!(\"discarding malformed komorebi notification: {error}\");\n              continue;\n            }\n          };\n\n          // match and filter on desired notifications\n        }\n      }\n      Err(error) =\u003e {\n        log::debug!(\"{error}\");\n      }\n    }\n  }\n\n}\n```\n\n## Subscription Event Notification Schema\n\nA [JSON Schema](https://json-schema.org/) of the event notifications emitted to\nsubscribers can be generated with the `komorebic notification-schema` command.\n\n## Socket Message Schema\n\nA [JSON Schema](https://json-schema.org/) of socket messages used to send\ninstructions to `komorebi` can be generated with the `komorebic socket-schema`\ncommand.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flgug2z%2Fkomorebi-for-mac","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flgug2z%2Fkomorebi-for-mac","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flgug2z%2Fkomorebi-for-mac/lists"}