merge: the history of komorebi-starlight

This commit is contained in:
LGUG2Z committed 2026-11-10 13:57:36 -08:00
commit c33464613c
378 files changed
+65068

No files matched your search

+23
View File
@@ -0,0 +1,23 @@
# build output
dist/
# generated types
.astro/
# dependencies
node_modules/
# logs
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
# environment variables
.env
.env.production
# macOS-specific files
.DS_Store
src/content/docs/reference/komorebic*.mdx
+4
View File
@@ -0,0 +1,4 @@
{
"recommendations": ["astro-build.astro-vscode"],
"unwantedRecommendations": []
}
+11
View File
@@ -0,0 +1,11 @@
{
"version": "0.2.0",
"configurations": [
{
"command": "./node_modules/.bin/astro dev",
"name": "Development server",
"request": "launch",
"type": "node-terminal"
}
]
}
+4
View File
@@ -0,0 +1,4 @@
# komorebi-starlight
Experimental unified documentation site for komorebi for Windows and macOS built
with Starlight.
+79
View File
@@ -0,0 +1,79 @@
// @ts-check
import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";
import { remarkHeadingId } from "remark-custom-heading-id";
// https://astro.build/config
export default defineConfig({
markdown: {
remarkPlugins: [remarkHeadingId],
},
integrations: [
starlight({
title: "komorebi",
logo: {
src: "./src/assets/watermelon.svg",
alt: "komorebi",
},
favicon: "/favicon.svg",
social: [
{
icon: "github",
label: "GitHub",
href: "https://github.com/LGUG2Z/komorebi",
},
],
sidebar: [
{
label: "About",
items: [
{ label: "Overview", slug: "about/overview" },
{ label: "Community", slug: "about/community" },
{ label: "Licensing", slug: "about/licensing" },
{ label: "Sponsorship", slug: "about/sponsorship" },
{ label: "Expectations", slug: "about/expectations" },
],
},
{
label: "Guides",
items: [
{ label: "Installation", slug: "guides/installation" },
{
label: "License Registration",
slug: "guides/license-registration",
},
{ label: "Quickstart", slug: "guides/quickstart" },
{ label: "Upgrades", slug: "guides/upgrades" },
{ label: "Known Issues", slug: "guides/known-issues" },
{ label: "Uninstallation", slug: "guides/uninstallation" },
],
},
{
label: "Usage",
items: [
{ label: "Windows", slug: "usage/windows" },
{ label: "Containers", slug: "usage/containers" },
{ label: "Workspaces", slug: "usage/workspaces" },
{ label: "Monitors", slug: "usage/monitors" },
{ label: "Layouts", slug: "usage/layouts" },
{ label: "Padding", slug: "usage/padding" },
{ label: "Layers", slug: "usage/layers" },
{ label: "Borders", slug: "usage/borders" }, // borders and colors
{ label: "Themes", slug: "usage/themes" }, // themes for borders (and the bar)
{ label: "Animations", slug: "usage/animations" }, // experimental animations
{ label: "Wallpapers", slug: "usage/wallpapers" }, // wallpapers per monitor/workspace and themegen
{ label: "Rules", slug: "usage/rules" }, // layout rules, behavior rules, matching rules, composite rules
],
},
{
label: "Reference",
autogenerate: { directory: "reference" },
},
{
label: "Common Workflows",
autogenerate: { directory: "common-workflows" },
},
],
}),
],
});
+8377
View File
File diff suppressed because it is too large. Load diff
+22
View File
@@ -0,0 +1,22 @@
{
"name": "komorebi-starlight",
"type": "module",
"version": "0.0.1",
"scripts": {
"generate:cli-reference": "node scripts/generate-cli-reference.cjs",
"dev": "npm run generate:cli-reference && astro dev",
"start": "npm run generate:cli-reference && astro dev",
"build": "npm run generate:cli-reference && astro build",
"preview": "astro preview",
"astro": "astro"
},
"dependencies": {
"@astrojs/check": "^0.9.6",
"@astrojs/starlight": "^0.37.1",
"astro": "^5.16.6",
"remark-custom-heading-id": "^2.0.0",
"sharp": "^0.34.5",
"typescript": "^5.9.3",
"wrangler": "^4.61.1"
}
}
+1
View File
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><text y="0.9em" font-size="90">🍉</text></svg>

After

Width:  |  Height:  |  Size: 111 B

@@ -0,0 +1,77 @@
#!/usr/bin/env node
const fs = require("fs");
const path = require("path");
const cliBaseDir = path.join(__dirname, "../src/data/cli");
const windowsDir = path.join(cliBaseDir, "windows");
const macosDir = path.join(cliBaseDir, "macos");
const windowsOutputFile = path.join(
__dirname,
"../src/content/docs/reference/komorebic-windows.mdx",
);
const macosOutputFile = path.join(
__dirname,
"../src/content/docs/reference/komorebic-macos.mdx",
);
// Helper to read markdown files from a directory
function readMarkdownFiles(dir) {
if (!fs.existsSync(dir)) {
return [];
}
return fs
.readdirSync(dir)
.filter((f) => f.endsWith(".md"))
.sort()
.map((file) => ({
name: file.replace(".md", ""),
content: fs.readFileSync(path.join(dir, file), "utf-8"),
}));
}
// Generate Windows reference
const windowsFiles = readMarkdownFiles(windowsDir);
if (windowsFiles.length > 0) {
let mdx = `---
title: komorebic (Windows)
description: Complete reference for all komorebic commands on Windows.
---
This page contains a complete reference of all \`komorebic\` commands on Windows.
`;
for (const { name, content } of windowsFiles) {
mdx += `### \`${name}\`\n\n`;
mdx += content + "\n\n";
}
fs.writeFileSync(windowsOutputFile, mdx);
console.log(
`Generated ${windowsOutputFile} with ${windowsFiles.length} commands`,
);
}
// Generate macOS reference
const macosFiles = readMarkdownFiles(macosDir);
if (macosFiles.length > 0) {
let mdx = `---
title: komorebic (macOS)
description: Complete reference for all komorebic commands on macOS.
---
This page contains a complete reference of all \`komorebic\` commands on macOS.
`;
for (const { name, content } of macosFiles) {
mdx += `### \`${name}\`\n\n`;
mdx += content + "\n\n";
}
fs.writeFileSync(macosOutputFile, mdx);
console.log(
`Generated ${macosOutputFile} with ${macosFiles.length} commands`,
);
}
if (windowsFiles.length === 0 && macosFiles.length === 0) {
console.log("No CLI documentation found in windows or macos directories");
}
Binary file not shown.

After

Width:  |  Height:  |  Size: 2.2 MiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 2.9 MiB

+1
View File
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><text y="0.9em" font-size="90">🍉</text></svg>

After

Width:  |  Height:  |  Size: 111 B

@@ -0,0 +1,51 @@
---
// src/components/KomorebiConfigPlatformLink.astro
interface Props {
command: string;
text?: string;
}
const { command, text } = Astro.props;
const displayText = text || `${command}`;
---
<a
class="config-platform-link"
data-command={command}
href={`/reference/komorebi-macos/#${command}`}
>{displayText}</a>
<script>
function getPlatform(): string {
const stored = localStorage.getItem('starlight-synced-tabs__platform');
if (!stored) return 'macos';
// Starlight stores as plain string (e.g., "Windows", "macOS")
const label = stored.toLowerCase();
if (label === 'windows' || label === 'win') return 'windows';
return 'macos';
}
function updateLinks() {
const platform = getPlatform();
document.querySelectorAll('.config-platform-link').forEach(link => {
const cmd = link.getAttribute('data-command');
link.setAttribute('href', `/reference/komorebi-${platform}/#${cmd}`);
});
}
// Update on page load
updateLinks();
// Listen for tab changes via storage event (works across tabs too)
window.addEventListener('storage', updateLinks);
// Listen for tab clicks on the same page
document.addEventListener('click', (e) => {
const target = e.target as HTMLElement;
const tab = target.closest('[role="tab"]');
if (tab) {
// Small delay to let Starlight update localStorage
setTimeout(updateLinks, 50);
}
});
</script>
@@ -0,0 +1,51 @@
---
// src/components/KomorebicPlatformLink.astro
interface Props {
command: string;
text?: string;
}
const { command, text } = Astro.props;
const displayText = text || `komorebic ${command}`;
---
<a
class="command-platform-link"
data-command={command}
href={`/reference/komorebic-macos/#${command}`}
>{displayText}</a>
<script>
function getPlatform(): string {
const stored = localStorage.getItem('starlight-synced-tabs__platform');
if (!stored) return 'macos';
// Starlight stores as plain string (e.g., "Windows", "macOS")
const label = stored.toLowerCase();
if (label === 'windows' || label === 'win') return 'windows';
return 'macos';
}
function updateLinks() {
const platform = getPlatform();
document.querySelectorAll('.command-platform-link').forEach(link => {
const cmd = link.getAttribute('data-command');
link.setAttribute('href', `/reference/komorebic-${platform}/#${cmd}`);
});
}
// Update on page load
updateLinks();
// Listen for tab changes via storage event (works across tabs too)
window.addEventListener('storage', updateLinks);
// Listen for tab clicks on the same page
document.addEventListener('click', (e) => {
const target = e.target as HTMLElement;
const tab = target.closest('[role="tab"]');
if (tab) {
// Small delay to let Starlight update localStorage
setTimeout(updateLinks, 50);
}
});
</script>
+7
View File
@@ -0,0 +1,7 @@
import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';
export const collections = {
docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
};
@@ -0,0 +1,23 @@
---
title: Community
description: About komorebi community spaces
tableOfContents: false
---
There is a [Discord server](https://discord.gg/mGkn66PHkx) available for
komorebi-related discussion, help, troubleshooting etc.
The Discord server includes the popular [Rice Rice
Baby](https://discord.com/channels/898554690126630914/1260648062158897284) forum
for users to share their desktops and configurations.
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 simple and passive way to contribute
financially to the project.
There is an [Awesome List](https://github.com/LGUG2Z/awesome-komorebi) which
showcases the many awesome projects that exist in the komorebi ecosystem.
@@ -0,0 +1,42 @@
---
title: Expectations
description: Setting Expectations
tableOfContents: false
---
## The Software
komorebi exists first and foremost to address my own needs, and as such it is built primarily according to my personal preferences; I don't care if i3 does something this way, or hyprland does something that way - komorebi will always do things my way.
komorebi is built on top of limited public APIs exposed by closed operating systems - it will likely never be as flashy as the window managers and desktop environments you will find on Linux.
I work on komorebi and provide support to users in my own time, at my own pace.
komorebi is not an open source project and I am not an open source software developer, so you should check any remnants of the open source culture of dehumanizing software maintainers at the door when you enter any komorebi community spaces.
This also applies if you have purchased an Individual Commercial Use License; you have purchased a license to use the software for commercial use _in the current state and as it is provided_. Nothing more, nothing less.
## Contributions
There have been a number of contributors to komorebi over the years, and contributions are accepted under the [Zero-Clause BSD License](https://www.tldrlegal.com/license/bsd-0-clause-license).
However, these days I am quite conservative when it comes to accepting contributions from new contributors due to the scale and scope of the project, the ubiquity and questionable quality of LLM-generated code, and the potential blast radius for breaking changes.
If you would like to contribute code to the project, please speak to me first on Discord in the `#development` channel instead of opening a drive-by PR.
## Support
Support is provided on a best-effort basis by myself and other volunteers in the community.
A lot of effort has gone into automatically generating correct and up-to-date documentation for komorebi's configuration schema and komorebic's CLI commands.
Providing support is by far the most time-consuming aspect of this project, so please make sure you exhaust all of the available documentation resources first _before_ reaching out to the community for support.
This means doing basic things like:
- Following the quickstart guides when you install the software
- Ensuring your configuration files contain valid JSON
- Validating your configurations against the provided JSONSchema files
- Searching through komorebic commands and reading the usage documentation
If and when you do reach out to the community for support, please be kind, be patient, and be respectful.
@@ -0,0 +1,48 @@
---
title: Licensing
description: About the Komorebi License
---
komorebi is [educational source
software](https://lgug2z.com/articles/educational-source-software/).
## Personal Use
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.
## 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).
Many employers reimburse software licensing costs, so submit a reimbursement
request to your employer with your receipt(s).
With mainstream corporate software reimbursement policies, the Individual
Commercial Use License functions as a mechanism to empower end users to mediate
corporate contributions to the financial sustainability of independent software.
> Extremely poetic to use detection of the presence of corporate spyware as
> leverage for redistribution of wealth, love this. [1]
>
> [1]: https://lobste.rs/s/vd7dgj/normalize_identifying_corporate#c_ufrklw
@@ -0,0 +1,53 @@
---
title: Overview
description: About komorebi
---
komorebi is an educational source cross-platform tiling window manager for
Windows and macOS.
komorebi allows you to control application windows, virtual workspaces and
display monitors with a CLI which can be used with any hotkey software.
komorebi aims to make *as few modifications as possible* to the operating
system and desktop environment by default.
## Design
komorebi only responds to operating system events and the messages it receives on a
dedicated socket.
komorebic is a CLI that writes messages on komorebi's socket.
komorebi doesn't handle any keyboard or mouse inputs directly.
This architecture, popularised by [bspwm](https://github.com/baskerville/bspwm)
on Linux and [yabai](https://github.com/koekeishiya/yabai) on macOS, is outlined
as follows:
```
PROCESS SOCKET
hotkey daemon --------> komorebic <------> komorebi
```
## Data Model
komorebi holds a list of physical monitors.
A monitor is a rectangle of the available work area which contains one or more
virtual workspaces.
A workspace holds a list of containers.
A container is a rectangle where one or more application windows can be
displayed.
This means that:
* Every monitor has its own collection of virtual workspaces
* Workspaces only know about containers and their dimensions, not about
individual application windows
* Every application window must belong to a container, even if that container
only contains one application window
* Many application windows can be stacked and cycled through in the same
container within a workspace
@@ -0,0 +1,23 @@
---
title: Sponsorship
description: About sponsoring komorebi
tableOfContents: false
---
komorebi is an [educational
source](https://lgug2z.com/articles/educational-source-software/) 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), the [Sameer
Project](https://chuffed.org/project/149178-sameer-project-x-mass-displacement-campaign)
or to contribute to a [Gaza Funds campaign](https://gazafunds.com) before you
consider sponsoring me on GitHub.
## Ways to Sponsor
* [GitHub Sponsors](https://github.com/sponsors/LGUG2Z)
* [Ko-fi](https://ko-fi.com/lgug2z)
* [YouTube Membership](https://www.youtube.com/@LGUG2Z/membership)
* BTC: `bc1qv73wzspc77k46uty4vp85x8sdp24mphvm58f6q`
@@ -0,0 +1,16 @@
---
title: Configuration Directory
description: How to set a custom configuration directory
---
You can specify a custom configuration directory by setting the `KOMOREBI_CONFIG_HOME` environment variable.
If you already have configuration files that you wish to keep, move them to the directory specified by the `KOMOREBI_CONFIG_HOME` environment variable.
You may reference `$KOMOREBI_CONFIG_HOME` in various options of the configuration when giving file paths, for example:
```json
{
"app_specific_configuration_path": "$KOMOREBI_CONFIG_HOME/applications.json"
}
```
@@ -0,0 +1,23 @@
---
title: Ghost Tiles
description: How to handle ghost tiles
---
import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro';
import KomorebiConfigPlatformLink from '../../../components/KomorebiConfigPlatformLink.astro';
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
<Tabs syncKey="platform">
<TabItem label="Windows">
</TabItem>
<TabItem label="macOS">
</TabItem>
</Tabs>
Sometimes you may experience an application which leaves "ghost tiles" on a workspace, where there is space reserved for a window but no window visible.
You will should add [ignore rules](/usage/rules/#ignore-rules) for these windows or applications using information from the <KomorebicPlatformLink command="visible-windows"/> command.
If you think that the rule you create should be a default rule for everybody, please make a contribution to the [komorebi-application-specific-configuration](https://github.com/LGUG2Z/komorebi-application-specific-configuration) repository.
@@ -0,0 +1,12 @@
---
title: Mouse Follows Focus
description: How to disable mouse follows focus
---
By default, the mouse will move to the center of the window when the focus is changed in a given direction. This behaviour is know as 'mouse follows focus'. This behaviour can be disabled in the `komorebi.json` configuration file.
```json
{
"mouse_follows_focus": false,
}
```
@@ -0,0 +1,189 @@
---
title: Multi Monitor Setup
description: How to setup komorebi for multiple monitors
---
import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro';
import KomorebiConfigPlatformLink from '../../../components/KomorebiConfigPlatformLink.astro';
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
<Tabs syncKey="platform">
<TabItem label="Windows">
</TabItem>
<TabItem label="macOS">
</TabItem>
</Tabs>
:::note
This does not apply to swapping between monitors (i.e. a laptop which either uses only an external display or only the internal display), which is not a multi-monitor workflow, but a complete monitor replacement workflow
When completely replacing monitors in this way, you should just use a hotkey to restart komorebi: `komorebic stop; sleep 1; komorebic start`
:::
## Two Static Monitors
To set up komorebi to work with multiple monitors, the first step is to add <KomorebiConfigPlatformLink command="monitors" text="independent configurations" /> for each monitor.
```json
{
"monitors": [
// monitor 1 at arary index 0
{
"workspaces": [
{
"name": "Monitor 1, Workspace 1",
"layout": "BSP"
},
{
"name": "Monitor 1, Workspace 2",
"layout": "VerticalStack"
},
{
"name": "Monitor 1, Workspace 3",
"layout": "HorizontalStack"
}
]
},
// monitor 2 at array index 1
{
"workspaces": [
{
"name": "Monitor 2, Workspace 1",
"layout": "BSP"
},
{
"name": "Monitor 2, Workspace 2",
"layout": "VerticalStack"
},
{
"name": "Monitor 2, Workspace 3",
"layout": "HorizontalStack"
}
]
}
]
}
```
In the above example, two monitors are configured. The first monitor is at array index 0, and the second monitor is at array index 1.
Now if you start komorebi with two monitors connected, the main monitor (as decided by the operating system) will use the configuration at array index 0 and the
secondary monitor will use the configuration at array index 1.
## Assigning Configurations to Specific Monitors
Let's say there are more monitors, or that you want to make sure a certain configuration is always applied to a certain monitor.
To do this we have to set our <KomorebiConfigPlatformLink command="display_index_preferences" text="display index preferences" />. The information required to do this can be retrieved using the <KomorebicPlatformLink command="monitor-information" /> command.
```jsonc
// ❯ komorebic monitor-information
[
{
"id": 6620935,
"name": "DISPLAY1",
"device": "BOE0A1C",
"device_id": "BOE0A1C-5&a2bea0b&0&UID512",
"serial_number_id": "0",
"size": {
"left": 0,
"top": 0,
"right": 1920,
"bottom": 1080
}
},
{
"id": 181932057,
"name": "DISPLAY2",
"device": "VSC8C31",
"device_id": "VSC8C31-5&18560b1f&0&UID4356",
"serial_number_id": "UEP174021562",
"size": {
"left": 0,
"top": -1080,
"right": 1920,
"bottom": 1080
}
}
]
```
In this case the setup is a laptop with a secondary monitor connected.
Once you know which monitor is which, the `serial_number_id` can be mapped to a specific monitor configuration array index.
```json
{
"display_index_preferences": {
"0": "0",
"1": "UEP174021562"
}
}
```
In the above example, the monitor configuration at array index `0` will be mapped to the monitor with the serial number `0`, and the monitor configuration at array index `1` will be mapped to the monitor with the serial number `UEP174021562`.
## Multiple Monitors in Different Locations
:::caution
You can't use the same config on two different monitors; dedicated configs are required for each monitor
:::
```jsonc
{
"display_index_preferences": {
"0": "HOME_MONITOR_1_ID",
"1": "HOME_MONITOR_2_ID",
"2": "WORK_MONITOR_1_ID",
"3": "WORK_MONITOR_2_ID"
},
"monitors": [
// HOME_MONITOR_1
{
"workspaces": [
// ...
]
},
// HOME_MONITOR_2
{
"workspaces": [
// ...
]
},
// WORK_MONITOR_1
{
"workspaces": [
// ...
]
},
// WORK_MONITOR_2
{
"workspaces": [
// ...
]
}
]
}
```
In the above example, although you will only ever have 2 monitors connected at any one time, the above configurations will still work in both physical locations.
## Recommended Display Settings on Microsoft Windows
In `Settings > System > Display > Multiple Displays`:
- Disable "Remember windows locations on monitor connection"
- Enable "Minimize windows when a monitor is disconnected"
## Important Workflow Details
* If you are using a laptop connected to one monitor at work and a different one at home, the work monitor and the home monitor are considered different monitors
* When you disconnect from work, komorebi will keep the work monitor cached
* You can still use a laptop alone without any monitor and if you need a window that was on the other monitor you can press the taskbar icon or use `alt + tab` to bring it to focus and that window will now be part of the laptop monitor
* If you then reconnect the work monitor, the cached version will be applied with all its windows (except any window(s) you might have moved to another monitor)
* If however, instead of reconnecting the work monitor, you connect the home monitor, then the work monitor will still remain cached, and komorebi will load the home monitor from the cache (if it exists)
* Sometimes when you disconnect/reconnect a monitor the event might be missed by komorebi, meaning that Windows will show you both monitors but komorebi won't know about the existence of one of them
* If you notice this type of weird behaviour, always run the <KomorebicPlatformLink command="monitor-information" /> command and validate if one of the monitors is missing
* To fix this you can try disconnecting and reconnecting the monitor again, or restarting komorebi
@@ -0,0 +1,19 @@
---
title: Multiple Bar Instances
description: How to launch multiple instances of komorebi-bar
---
If you would like to run multiple instances of `komorebi-bar` to target different monitors, it is possible to do so by maintaining multiple `komorebi.bar.json` configuration files and specifying their paths in your configuration file.
You may also use or `$KOMOREBI_CONFIG_HOME` when specifying the paths.
```json
{
"bar_configurations": [
"$KOMOREBI_CONFIG_HOME/komorebi.bar.monitor1.json",
"$KOMOREBI_CONFIG_HOME/komorebi.bar.monitor2.json"
]
}
```
The main difference between different `komorebi.bar.json` files will be the value of `monitor.index` which is used to target the monitor for each instance of `komorebi-bar`.
@@ -0,0 +1,13 @@
---
title: Remove All Gaps
description: How to remove all gaps
---
If you would like to remove all gaps by default, both between windows themselves, and between the monitor edges and the windows, you can set the following configuration options:
```json
{
"default_workspace_padding": 0,
"default_container_padding": -1,
}
```
@@ -0,0 +1,185 @@
---
title: Installation
description: How to install komorebi
---
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
Packages are available install via [Scoop](https://scoop.sh/#/apps?q=komorebi)
and [WinGet](https://winget.run/pkg/LGUG2Z/komorebi) on Windows, and
[Homebrew](https://github.com/LGUG2Z/homebrew-tap) and
[Nix](https://github.com/KomoCorp/komorebi-for-mac) on macOS.
You may also build from source on both platforms.
:::note[komorebi for Mac availability]
Early access nightly releases of komorebi for Mac are available to [GitHub Sponsors](https://github.com/sponsors/LGUG2Z) on the $10/month tier.
:::
## Suggested system settings
<Tabs syncKey="platform">
<TabItem label="Windows">
It is highly recommended that you enable support for long paths in Windows by
running the following command in an Administrator Terminal before installing
komorebi.
```powershell
Set-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1
```
It is also highly recommended that you enable the "Turn off all unnecessary
animations (when possible)" option in "Control Panel > Ease of Access > Ease of
Access Centre / Make the computer easier to see" for the best performance with
komorebi.
</TabItem>
<TabItem label="macOS">
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.
</TabItem>
</Tabs>
## Installation via Package Managers
:::note[Windows $Env:PATH Issues]
Issues with `komorebi` and related commands not being recognized in the
terminal ultimately come down to the `$Env:PATH` environment variable not being
correctly configured by your package manager and **should not** be raised as
bugs or issues either on the GitHub repository or Discord server.
:::
<Tabs syncKey="package-manager">
<TabItem label="Scoop">
```bash title="Add the extras bucket"
scoop bucket add extras
```
```bash title="Install komorebi and whkd"
scoop install komorebi whkd
```
</TabItem>
<TabItem label="WinGet">
```bash title="Install komorebi and whkd"
winget install LGUG2Z.komorebi
winget install LGUG2Z.whkd
```
:::note
You must restart your terminal after installing with WinGet.
:::
</TabItem>
<TabItem label="Homebrew">
```bash title="Add lgug2z/tap"
brew tap lgug2z/tap
```
```bash title="Install komorebi and skhd"
brew install lgug2z/tap/komorebi-for-mac
brew install skhd
```
</TabItem>
<TabItem label="Homebrew (nightly)">
```bash title="Add lgug2z/tap"
brew tap lgug2z/tap
```
```bash title="Install komorebi and skhd"
brew install lgug2z/tap/komorebi-for-mac-nightly
brew install skhd
```
</TabItem>
<TabItem label="Nix">
Ensure that your system Flake is configured to use your GitHub token so that you
can add a private repository as an input.
```nix title="flake.nix"
{
nix = {
settings = {
access-tokens = [
"github.com=YOUR ACCESS TOKEN"
];
};
};
}
```
Add the repository as an input:
```nix title="flake.nix"
{
inputs.komorebi-for-mac.url = "github:KomoCorp/komorebi-for-mac";
}
```
Add the overlay to your system's nixpkgs configuration:
```nix title="flake.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 title="flake.nix"
{
environment.systemPackages = [
pkgs.komorebi-full
];
}
```
</TabItem>
</Tabs>
## Building From Source
Make sure you have installed [`rustup`](https://rustup.rs), a stable Rust
compiler toolchain, and if compiling on Windows, the Visual Studio [Visual
Studio prerequisites](https://rust-lang.github.io/rustup/installation/windows-msvc.html).
Clone the git repository, enter the directory, and build the following binaries:
```bash title="Build and install the individual binaries"
# Windows and macOS
cargo +stable install --path komorebi --locked
cargo +stable install --path komorebic --locked
cargo +stable install --path komorebi-bar --locked
# Windows only
cargo +stable install --path komorebi-shortcuts --locked
cargo +stable install --path komorebic-no-console --locked
cargo +stable install --path komorebi-gui --locked
```
The binaries will be installed to `$HOME/.cargo/bin`. It is your responsibility
to ensure this directory is in your `$PATH`.
You can follow similar instructions to build
[`whkd`](https://github.com/LGUG2Z/whkd) from source on Windows.
## Offline Installation
Windows users can download the latest
[komorebi](https://github.com/LGUG2Z/komorebi/releases) and
[whkd](https://github.com/LGUG2Z/whkd/releases) MSI installers on an
internet-connected computer, then copy them to an offline machine to install.
@@ -0,0 +1,26 @@
---
title: Known Issues
description: A license registration guide for komorebi.
---
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
If you're interested in working on any of these issues you can drop by the
[#development](https://discord.gg/mGkn66PHkx) channel on the Discord.
<Tabs syncKey="platform">
<TabItem label="Windows">
* Resizing with the mouse is janky - This probably needs a whole rewrite but I don't use this feature enough to do it myself
* The Scrolling layout is limited to setups with a single monitor - This is to avoid bleeding windows into other monitors. There is a workaround which technically works which involves resizing windows at the edges when they move in and out of the viewport, but Electron sucks and every Electron app gives the black screen of death when resized like this
</TabItem>
<TabItem label="macOS">
* The flow for manually adding Accessibility and Screen Recording permissions sucks - I am open to ideas on how to improve this
* Fullscreen windows aren't supported and break the state - I don't have any plans or ideas on how to support them smoothly but I'm open to hear yours
* Application hiding isn't supported and breaks the state - This will probably never be supported and I suggest disabling the CMD+H hotkey entirely
* The hotkey CMD+H is used by macOS to hide the application - I suggest disabling it entirely
* Resizing with the mouse is janky - This probably needs a whole rewrite but I don't use this feature enough to do it myself
* Resizing windows with animations enabled is a train wreck - I suggest keeping animations disabled if you like to use the mouse to resize and move windows
* The Scrolling layout is limited to setups with a single monitor - This is due to the lack of public window hiding API which komorebi works around by stashing windows in hidden corners, which would bleed "hidden" windows into other monitors
</TabItem>
</Tabs>
@@ -0,0 +1,41 @@
---
title: License Registration
description: A license registration guide for komorebi.
---
komorebi [identifies corporate devices](https://lgug2z.com/articles/normalize-identifying-corporate-devices-in-your-software/) [on a best-effort
basis](https://lobste.rs/s/vd7dgj/normalize_identifying_corporate) through the
detection of mobile device management enrollment.
## License Registration
If you are using komorebi on a device enrolled in mobile device management, you
will receive a pop-up when you run `komorebic start` reminding you that the
[Komorebi License](https://github.com/LGUG2Z/komorebi-license) does not permit
any kind of commercial use.
You can remove this pop-up by running `komorebic license <email>` with the email
associated with your Individual Commercial Use License. A single HTTP request
will be sent with the given email address to verify license validity.
## Students on Windows Machines
If you have an device provided by your educational institution, or a personal
device which you have been forced to enroll in "Bring Your Own Device" (BYOD)
MDM, you can email me (my_github_username _at_ fastmail _dot_ com) from the
address associated with your institution with the subject "komorebi - student
with an MDM device", and I will be able to remove the splash intended for
corporate users
This is currently a manual process - most days this shouldn't take more than
12h, and you will receive an email reply from me when the process is complete.
If you haven't had a reply to your email within 24h you can reach out to me on
[Discord](https://discord.gg/mGkn66PHkx).
## Edge Cases on Windows
There are always edge cases, and if you are using komorebi for personal use and
think you have been caught up in one of them you can email me with a screenshot
of the output from `dsregcmd /status` and a few lines about why the device you
are using is enrolled in (BYOD) MDM and I can usually add an override for you.
@@ -0,0 +1,76 @@
---
title: Quickstart
description: A quickstart guide for komorebi
---
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
Tiling window managers in general are very complex pieces of software.
In an attempt to reduce some of the initial configuration burden for users who
are looking to try out the software for the first time, example configurations
are provided and updated whenever appropriate.
Run the following command to download example configuration files for
komorebi, whkd (on Windows) and skhd (on macOS).
Pay attention to the output of the command to see where the example files have
been downloaded.
```shell title="Install the example configurations"
komorebic quickstart
```
:::note[macOS Permissions]
The `quickstart` command will also prompt you to grant komorebi and the terminal
emulator you are start komorebi with the permissions it requires to run, and
will open the following System Settings tabs for you:
* Settings -> Privacy & Security -> Accessibility
* Settings -> Privacy & Security -> Screen & System Audio Recording
komorebi will not run unless it has the required permissions.
:::
## Starting komorebi
<Tabs syncKey="platform">
<TabItem label="Windows">
With the example configurations downloaded, you can now start `komorebi`,
`komorebi-bar` and `whkd`.
```bash title="Start komorebi, komorebi-bar and whkd in the background"
komorebic start --whkd --bar
```
If you decide you don't like the komorebi-bar and want to use a different bar,
you can kill the bar, and next time you start komorebi, omit the `--bar` flag.
```bash title="Kill the komorebi-bar and start komorebi without it"
komorebic kill --bar
komorebic start --whkd
```
</TabItem>
<TabItem label="macOS">
With the example configurations downloaded, you can now start `komorebi`,
`komorebi-bar` and `skhd`.
```bash title="Start komorebi, komorebi-bar in the background"
komorebic start --bar
```
```bash title="Start skhd in the foreground"
skhd --config ~/.config/komorebi/skhdrc
```
If you decide you don't like the komorebi-bar and want to use a different bar,
you can kill the bar, and next time you start komorebi, omit the `--bar` flag.
```bash title="Kill the komorebi-bar and start komorebi without it"
pkill komorebi-bar
komorebic start
```
</TabItem>
</Tabs>
@@ -0,0 +1,61 @@
---
title: Uninstallation
description: How to uninstall komorebi
---
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
Before upgrading, ensure that komorebi and the komorebi bar have been stopped.
If you wish to uninstall whkd on Windows or skhd on macOS, ensure they have also
been stopped.
<Tabs syncKey="package-manager">
<TabItem label="Scoop">
```bash title="Uninstall komorebi and whkd"
scoop uninstall komorebi whkd
```
</TabItem>
<TabItem label="WinGet">
```bash title="Uninstall komorebi and whkd"
winget uninstall LGUG2Z.komorebi
winget uninstall LGUG2Z.wkhd
```
</TabItem>
<TabItem label="Homebrew">
```bash title="Uninstall komorebi and skhd"
brew uninstall lgug2z/tap/komorebi-for-mac
brew uninstall skhd
```
</TabItem>
<TabItem label="Homebrew (nightly)">
```bash title="Uninstall komorebi and skhd"
brew uninstall lgug2z/tap/komorebi-for-mac-nightly
brew uninstall skhd
```
</TabItem>
</Tabs>
Finally, you can run the following commands to clean up files created by the
`quickstart` command and any other runtime files:
<Tabs syncKey="platform">
<TabItem label="Windows">
```bash title="Clean up runtime files"
rm $Env:USERPROFILE/komorebi.json
rm $Env:USERPROFILE/applications.json
rm $Env:USERPROFILE/.config/whkdrc
rm -r -Force $Env:LOCALAPPDATA/komorebi
```
</TabItem>
<TabItem label="macOS">
```bash title="Clean up runtime files"
rm -rf ~/.config/komorebi
rm -rf "~/Library/Application Support/komorebi"
```
</TabItem>
</Tabs>
@@ -0,0 +1,46 @@
---
title: Upgrades
description: How to upgrade komorebi
---
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
Before upgrading, ensure that komorebi and the komorebi bar have been stopped.
```bash title="Stop komorebi and komorebi bar"
komorebic stop --bar
```
Once the processes have been stopped, you can upgrade komorebi using your
package manager.
<Tabs syncKey="package-manager">
<TabItem label="Scoop">
```bash title="Upgrade komorebi"
scoop update komorebi
```
</TabItem>
<TabItem label="WinGet">
```bash title="Upgrade komorebi"
winget upgrade LGUG2Z.komorebi
```
</TabItem>
<TabItem label="Homebrew">
```bash title="Upgrade komorebi"
brew update
brew upgrade lgug2z/tap/komorebi-for-mac
```
</TabItem>
<TabItem label="Homebrew (nightly)">
```bash title="Upgrade komorebi"
brew update
brew upgrade lgug2z/tap/komorebi-for-mac-nightly
```
</TabItem>
</Tabs>
Once the upgrade is completed you can confirm that you have the latest version
by running `komorebic --version`, and then start it with `komorebic start --whkd --bar`.
+13
View File
@@ -0,0 +1,13 @@
---
title: Welcome
description: komorebi - The cross-platform tiling window manager for Windows and macOS
tableOfContents: false
---
komorebi is an educational source cross-platform tiling window manager for Windows and macOS.
![screenshot](https://user-images.githubusercontent.com/13164844/184027064-f5a6cec2-2865-4d65-a549-a1f1da589abf.png)
This new documentation site is still a work in progress. Please also refer to
[the previous documentation site](https://lgug2z.github.io/komorebi/) which has a
wealth of information which will soon be integrated here.
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,47 @@
---
title: Animations
description: Configuring animations
---
import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro';
import KomorebiConfigPlatformLink from '../../../components/KomorebiConfigPlatformLink.astro';
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
<Tabs syncKey="platform">
<TabItem label="Windows">
</TabItem>
<TabItem label="macOS">
</TabItem>
</Tabs>
Animations are an experimental feature in both komorebi for Windows and komorebi for Mac.
## Enable Animations
Animations are <KomorebiConfigPlatformLink command="animationsconfig-enabled" text="disabled by default"/> in the configuration file.
```json
{
"animation": {
"enabled": true,
"duration": 250,
"fps": 120,
"style": "EaseOutSine"
}
}
```
Animations can be enabled (and disabled) in realtime using the <KomorebicPlatformLink command="animation"/> command.
## Animation Duration
The duration of animations can be <KomorebiConfigPlatformLink command="animationsconfig-duration" text="configured in milliseconds"/> and defaults to `250`.
## Animation FPS
The FPS of animations can be <KomorebiConfigPlatformLink command="animationsconfig-fps" text="configured to match your display refresh rate"/> and defaults to `60`. Note that increasing this value will increase CPU usage.
## Animation Style
The Animation style can be configured using <KomorebiConfigPlatformLink command="animationstyle" text="Cubic Bézier curves"/> and defaults to `Linear`.
@@ -0,0 +1,53 @@
---
title: Borders
description: Configuring borders
---
import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro';
import KomorebiConfigPlatformLink from '../../../components/KomorebiConfigPlatformLink.astro';
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
<Tabs syncKey="platform">
<TabItem label="Windows">
</TabItem>
<TabItem label="macOS">
</TabItem>
</Tabs>
Borders are an experimental feature in both komorebi for Windows and komorebi for Mac.
## Enable Borders
Borders are <KomorebiConfigPlatformLink command="border" text="enabled by default"/> in the configuration file.
Borders can be enabled (and disabled) in realtime using the <KomorebicPlatformLink command="border"/> command.
## Border Width
Border width is configured using a mixture of the <KomorebiConfigPlatformLink command="border_width" text="width"/> and <KomorebiConfigPlatformLink command="border_offset" text="offset"/> configuration options.
These options can be set in realtime using the <KomorebicPlatformLink command="border-width"/> and <KomorebicPlatformLink command="border-offset"/> commands.
The border offset is the distance out from the edge of the window. Setting this to a greater value will increase the size of the border (the distance of the outer edge of the border from the outer edge of the window)
The border width is the width of the border from the border offset towards the edge of the window. Setting this to a greater value will increase the color fill of the border (towards the outer edge of the window).
It is safe to set the border width to a value which would fill inwards past the outer edge of the window, as the border will be drawn behind the window. This can be useful when running on an operating system which does not enforce a consistent radius for windows with rounded corners.
## Border Colours
:::note[Border Colours and Themes]
[Themes](/usage/themes) take priority over border colours - make sure you unset any themes in your configuration file before trying to configure individual border colours.
:::
komorebi uses border colours to indicate different window container states:
- <KomorebiConfigPlatformLink command="bordercolours-single" text="Single"/> - an active container with a single window
- <KomorebiConfigPlatformLink command="bordercolours-stack" text="Stack"/> - an active container with multiple stacked windows
- <KomorebiConfigPlatformLink command="bordercolours-monocle" text="Monocle"/> - an active container in monocle mode
- <KomorebiConfigPlatformLink command="bordercolours-floating" text="Floating"/> - an active floating window
- <KomorebiConfigPlatformLink command="bordercolours-unfocused" text="Unfocused"/> - an unfocused window container
- <KomorebiConfigPlatformLink command="bordercolours-unfocused-locked" text="Unfocused/Locked"/> - an unfocused window container in the locked state
These border colours can be <KomorebiConfigPlatformLink command="border_colours" text="configured"/> using either RGB or hexadecimal values.
@@ -0,0 +1,48 @@
---
title: Containers
description: Manipulating containers
---
import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro';
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
<Tabs syncKey="platform">
<TabItem label="Windows">
</TabItem>
<TabItem label="macOS">
</TabItem>
</Tabs>
## Container Stacks
Container stacks can be manipulated in the following ways.
### Stacking
#### Directional Stacking
The focused window can be stacked on top of another window in a relative direction using the <KomorebicPlatformLink command="stack" /> command.
#### Consolidation
All windows on a workspace can be consolidated into a single stack using the <KomorebicPlatformLink command="stack-all" /> command.
### Focus
The focused window at the top of a container stack can be cycled using the <KomorebicPlatformLink command="cycle-stack" /> command.
### Unstacking
#### Single Windows
The focused window at the top of a container stack can be popped into an independent container using the <KomorebicPlatformLink command="unstack" /> command.
#### All Windows
All windows in a stack can be split into independent containers using the <KomorebicPlatformLink command="unstack-all" /> command.
## Monocle Containers
A container can be set as the monocle container, hiding all other containers on the workspace, by using the <KomorebicPlatformLink command="toggle-monocle" /> command. This command is reversible.
@@ -0,0 +1,33 @@
---
title: Layers
description: Understanding workspace layers
---
import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro';
import KomorebiConfigPlatformLink from '../../../components/KomorebiConfigPlatformLink.astro';
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
<Tabs syncKey="platform">
<TabItem label="Windows">
</TabItem>
<TabItem label="macOS">
</TabItem>
</Tabs>
komorebi has two distinct workspace layers for tiling and floating windows.
## Layer Selection
Whenever a layer is toggled, the windows associated with that layer will be brought to the foreground.
The layer for the focused workspace can be toggled in realtime using the <KomorebicPlatformLink command="toggle-workspace-layer"/> command.
## Floating Layer Behaviour
The <KomorebiConfigPlatformLink command="floatinglayerbehaviour" text="floating layer behaviour"/> can be set <KomorebiConfigPlatformLink command="monitorconfig-floating_layer_behaviour" text="globally"/>, at the <KomorebiConfigPlatformLink command="monitorconfig-floating_layer_behaviour" text="monitor-level"/> and at the <KomorebiConfigPlatformLink command="workspaceconfig-floating_layer_behaviour" text="workspace-level"/> to determine if new windows opened while the floating layer is active shout float or be tiled.
## Floating Layer Placement
The <KomorebiConfigPlatformLink command="placement" text="floating layer placement"/> is set <KomorebiConfigPlatformLink command="monitorconfig-floating_layer_placement" text="globally"/> and determines where a new window is placed is the floating layer behaviour is set to make new windows float.
@@ -0,0 +1,268 @@
---
title: Layouts
description: Configuring layouts
---
import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro';
import KomorebiConfigPlatformLink from '../../../components/KomorebiConfigPlatformLink.astro';
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
<Tabs syncKey="platform">
<TabItem label="Windows">
</TabItem>
<TabItem label="macOS">
</TabItem>
</Tabs>
## Layout Selection
<KomorebiConfigPlatformLink command="defaultlayout" text="Layouts"/> are selected using the <KomorebiConfigPlatformLink command="workspaceconfig-layout" text="layout configuration option"/> for each workspace and can be pre-configured as <KomorebiConfigPlatformLink command="workspaceconfig-layout_flip" text="layout_flip" text="flipped on specific axis"/>.
Certain layouts have <KomorebiConfigPlatformLink command="workspaceconfig-layout_options" text="options"/> which adjust how they arrange containers on a workspace.
The layout for the focused workspace switched in realtime using the <KomorebicPlatformLink command="change-layout"/> command.
The layout for the focused workspace can be cycled in realtime using the <KomorebicPlatformLink command="cycle-layout"/> command.
The layout for the a workspace identified by monitor and workspace index can be set in realtime using the <KomorebicPlatformLink command="workspace-layout"/> command.
The layout for the a workspace by name can be set in realtime using the <KomorebicPlatformLink command="named-workspace-layout"/> command.
## Layout Rules
<KomorebiConfigPlatformLink command="workspaceconfig-layout_rules" text="Layout rules"/> are used to automatically change the layout on a specified workspace when a threshold of window containers is met.
```json
{
"monitors": [
{
"workspaces": [
{
"name": "workspace with layout rules",
"layout_rules": {
"1": "BSP",
"4": "UltrawideVerticalStack",
"7": "Grid"
}
}
]
}
]
}
```
In the above example
* When there are between 1 and 3 window containers on the workspace, the BSP layout will be applied
* When there are between 4 and 6 window containers on the workspace, the UltrawideVerticalStack layout will be applied
* When there are between 7 or more window containers on the workspace, the Grid layout will be applied
Layout rules can be cleared from a workspace by monitor and workspace index using the <KomorebicPlatformLink command="clear-workspace-layout-rules"/> command, and by workspace name using the <KomorebiConfigPlatformLink command="clear-named-workspace-layout-rules"/> command.
## Layout Ratios
<KomorebiConfigPlatformLink command="layoutoptions" text="Layout options" /> can be used to define custom split ratios for various layouts.
BSP layout with default 50/50 splits
![Before layout ratios](../../../assets/layout-ratios_before.png)
BSP layout with `column_ratios: [0.7]` and `row_ratios: [0.6]`:
![After layout ratios](../../../assets/layout-ratios_after.png)
### Example Configuration
```json
{
"monitors": [
{
"workspaces": [
{
"name": "main",
"layout_options": {
"column_ratios": [0.3, 0.4],
"row_ratios": [0.4, 0.3]
}
}
]
}
]
}
```
You can specify up to 5 ratio values (defined by `MAX_RATIOS` constant). Each value should be between 0.1 and 0.9
(defined by `MIN_RATIO` and `MAX_RATIO` constants). Values outside this range are automatically clamped.
Columns or rows without a specified ratio will share the remaining space equally.
### Usage by Layout
| Layout | `column_ratios` | `row_ratios` |
|--------|-----------------|--------------|
| **Columns** | Width of each column | - |
| **Rows** | - | Height of each row |
| **Grid** | Width of each column (rows are equal height) | - |
| **BSP** | `[0]` as horizontal split ratio | `[0]` as vertical split ratio |
| **VerticalStack** | `[0]` as primary column width | Stack row heights |
| **RightMainVerticalStack** | `[0]` as primary column width | Stack row heights |
| **HorizontalStack** | Stack column widths | `[0]` as primary row height |
| **UltrawideVerticalStack** | `[0]` center, `[1]` left column | Tertiary stack row heights |
### Examples
#### Columns Layout with Custom Widths
Create 3 columns with 30%, 40%, and 30% widths:
```json
{
"layout_options": {
"column_ratios": [0.3, 0.4]
}
}
```
:::note
The third column automatically gets the remaining 30%
:::
#### Rows Layout with Custom Heights
Create 3 rows with 20%, 50%, and 30% heights:
```json
{
"layout_options": {
"row_ratios": [0.2, 0.5]
}
}
```
:::note
The third column automatically gets the remaining 30%
:::
#### Grid Layout with Custom Column Widths
Grid with custom column widths (rows within each column are always equal height):
```json
{
"layout_options": {
"column_ratios": [0.4, 0.6]
}
}
```
:::note
The Grid layout only supports `column_ratios`. Rows within each column are always divided equally because the number of rows per column varies dynamically based on window count
:::
#### VerticalStack with Custom Ratios
Primary column takes 60% width, and the stack rows are split 30%/70%:
```json
{
"layout_options": {
"column_ratios": [0.6],
"row_ratios": [0.3]
}
}
```
:::note
The second row automatically gets the remaining 70%
:::
#### HorizontalStack with Custom Ratios
Primary row takes 70% height, and the stack columns are split 40%/60%:
```json
{
"layout_options": {
"row_ratios": [0.7],
"column_ratios": [0.4]
}
}
```
:::note
The second column automatically gets the remaining 60%
:::
#### UltrawideVerticalStack with Custom Ratios
Center column at 50%, left column at 25% (remaining 25% goes to tertiary stack),
with tertiary rows split 40%/60%:
```json
{
"layout_options": {
"column_ratios": [0.5, 0.25],
"row_ratios": [0.4]
}
}
```
:::note
The second row automatically gets the remaining 60%
:::
#### BSP Layout with Custom Split Ratios
Use separate ratios for horizontal (left/right) and vertical (top/bottom) splits:
```json
{
"layout_options": {
"column_ratios": [0.6],
"row_ratios": [0.3]
}
}
```
- `column_ratios[0]`: Controls all horizontal splits (left window gets 60%, right gets 40%)
- `row_ratios[0]`: Controls all vertical splits (top window gets 30%, bottom gets 70%)
:::note
BSP only uses the first value (`[0]`) from each ratio array. This single ratio is applied consistently to all splits of that type throughout the layout. Additional values in the arrays are ignored
:::
### Progressive Ratio Behavior
Ratios are applied progressively as windows are added. For example, with `row_ratios: [0.3, 0.5]` in a VerticalStack:
| Windows in Stack | Row Heights |
|------------------|-------------|
| 1 | 100% |
| 2 | 30%, 70% (remainder) |
| 3 | 30%, 50%, 20% (remainder) |
| 4 | 30%, 50%, 10%, 10% (remainder split equally) |
| 5 | 30%, 50%, 6.67%, 6.67%, 6.67% |
### Automatic Ratio Truncation
When ratios sum to 100% (or more), they are automatically truncated at config load time.
For example, if you configure `column_ratios: [0.4, 0.3, 0.3]` (sums to 100%), the last ratio (0.3) is automatically removed, resulting in effectively `[0.4, 0.3]`. This ensures there's always remaining space for the last window.
| Configured Ratios | Effective Ratios | Reason |
|-------------------|------------------|--------|
| `[0.3, 0.4]` | `[0.3, 0.4]` | Sum is 0.7, below 1.0 |
| `[0.4, 0.3, 0.3]` | `[0.4, 0.3]` | Sum would be 1.0, last ratio truncated |
| `[0.5, 0.5]` | `[0.5]` | Sum would be 1.0, last ratio truncated |
| `[0.6, 0.5]` | `[0.6]` | Sum would exceed 1.0, last ratio truncated |
This ensures the layout always fills 100% of the available space and new windows are never placed outside the visible area.
### Notes
- Ratios are clamped between 0.1 and 0.9 (prevents zero-sized windows and ensures space for other windows)
- Default ratio is 0.5 (50%) when not specified, except for UltrawideVerticalStack secondary column which defaults to 0.25 (25%)
- Ratios are applied **progressively** - a ratio is only used when there are more windows to place after the current one
- The **last window always takes the remaining space**, regardless of defined ratios
- **Ratios that would sum to 100% or more are automatically truncated** at config load time to ensure there's always space for additional windows
- Unspecified ratios default to sharing the remaining space equally
- You only need to specify the ratios you want to customize; trailing values can be omitted
@@ -0,0 +1,52 @@
---
title: Monitors
description: Configuring monitors
---
import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro';
import KomorebiConfigPlatformLink from '../../../components/KomorebiConfigPlatformLink.astro';
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
<Tabs syncKey="platform">
<TabItem label="Windows">
</TabItem>
<TabItem label="macOS">
</TabItem>
</Tabs>
## Focus
Monitors can be focused in the following ways.
### By Index
Monitors can be focused by index using the <KomorebicPlatformLink command="focus-monitor"/> command, or by a mixture of monitor index and workspace index using the <KomorebicPlatformLink command="focus-monitor-workspace"/> command.
### Cycle Direction
Monitors can be focused in a cyclic direction using the <KomorebicPlatformLink command="cycle-monitor" /> command.
### By Cursor
Monitors can be focused by cursor position using the <KomorebicPlatformLink command="focus-monitor-at-cursor"/> command.
## Boundary Behaviour
### Cross Boundary Behaviour
There are two behaviours which can be configured when an action on a window container would cross a monitor boundary:
* <KomorebiConfigPlatformLink command="crossboundarybehaviour" text="Workspace"/> - attempts to perform the action across a workspace boundary on the same monitor
* <KomorebiConfigPlatformLink command="crossboundarybehaviour" text="Monitor"/> - attempts to perform the action across a monitor boundary
### Cross Monitor Move Behaviour
There are three behaviours which can be configured when attempting to move a window across a monitor boundary:
* <KomorebiConfigPlatformLink command="movebehaviour" text="Swap"/> the window container with the window container at the edge of the adjacent monitor
* <KomorebiConfigPlatformLink command="movebehaviour" text="Insert"/> the window container into the focused workspace on the adjacent monitor
* <KomorebiConfigPlatformLink command="movebehaviour" text="NoOp"/> (do nothing) if trying to move a window container in the direction of an adjacent monitor
This behaviour can be changed in realtime using the <KomorebicPlatformLink command="cross-monitor-move-behaviour"/> command.
@@ -0,0 +1,101 @@
---
title: Padding
description: Configuring padding
---
import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro';
import KomorebiConfigPlatformLink from '../../../components/KomorebiConfigPlatformLink.astro';
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
<Tabs syncKey="platform">
<TabItem label="Windows">
</TabItem>
<TabItem label="macOS">
</TabItem>
</Tabs>
## Workspace Padding
Workspace padding (the padding between the workspace and the screen edges) can be manipulated on three different levels:
* The <KomorebiConfigPlatformLink command="default_workspace_padding" text="default workspace padding"/> which will apply to all workspaces unless explicitly configured otherwise on a workspace
* The <KomorebiConfigPlatformLink command="monitorconfig-workspace_padding" text="monitor-level workspace padding"/> which will apply to all workspaces on a monitor unless explicitly configured otherwise on a workspace
* The <KomorebiConfigPlatformLink command="workspaceconfig-workspace_padding" text="workspace-level workspace padding"/> which will take priority over all other padding configurations for the specified workspace
The workspace padding on the focused workspace can be adjusted (increased or decreased) in realtime using the <KomorebicPlatformLink command="adjust-workspace-padding"/> command.
The workspace padding on the focused workspace can be set to a specific value in realtime using the <KomorebicPlatformLink command="focused-workspace-padding"/> command.
The workspace padding on for a workspace identified by monitor and workspace index can set to a specific value in realtime using the <KomorebicPlatformLink command="workspace-padding"/> command.
The workspace padding on for a named workspace can set to a specific value in realtime using the <KomorebicPlatformLink command="named-workspace-padding"/> command.
## Container Padding
Container padding (the padding between each container on a workspace) can be manipulated on three different levels:
* The <KomorebiConfigPlatformLink command="default_container_padding" text="default container padding"/> which will apply to all workspaces unless explicitly configured otherwise on a workspace
* The <KomorebiConfigPlatformLink command="monitorconfig-container_padding" text="monitor-level container padding"/> which will apply to all workspaces on a monitor unless explicitly configured otherwise on a workspace
* The <KomorebiConfigPlatformLink command="workspaceconfig-container_padding" text="workspace-level container padding"/> which will take priority over all other padding configurations for the specified workspace
The container padding on the focused workspace can be adjusted (increased or decreased) in realtime using the <KomorebicPlatformLink command="adjust-container-padding"/> command.
The container padding on the focused workspace can be set to a specific value in realtime using the <KomorebicPlatformLink command="focused-workspace-container-padding"/> command.
The container padding on for a workspace identified by monitor and workspace index can set to a specific value in realtime using the <KomorebicPlatformLink command="container-padding"/> command.
The container padding on for a named workspace can set to a specific value in realtime using the <KomorebicPlatformLink command="named-workspace-container-padding"/> command.
## Offsets
### Work Area Offsets
Work area (the area in which komorebi will manage windows) offsets can be manipulated on three different levels:
* The <KomorebiConfigPlatformLink command="global_work_area_offset" text="global work area offset"/> which will apply to all monitors and workspaces unless explicitly configured otherwise on a monitor or workspace
* The <KomorebiConfigPlatformLink command="monitorconfig-work_area_offset" text="monitor-level work area offset"/> which will apply to workspaces on a monitor unless explicitly configured otherwise on a workspace
* The <KomorebiConfigPlatformLink command="workspaceconfig-work_area_offset" text="workspace-level work area offset"/> which will take priority over all other work area offset configurations for the specified workspace
The global work area offset can be set in realtime using the <KomorebicPlatformLink command="global-work-area-offset"/> command.
The monitor work area offset can be set for a monitor identified by monitor index in realtime using the <KomorebicPlatformLink command="monitor-work-area-offset"/> command.
The workspace work area offset can be set for a workspace identified by workspace and monitor index in realtime using the <KomorebicPlatformLink command="workspace-work-area-offset"/> command.
### Dynamic Window-Based Work Area Offsets
Work area offsets can also be dynamically adjusted based on the number of window containers present on a workspace.
This is particularly useful for ultrawide monitors when only a single window container is visible, allowing offsets to be added to the left and right to constrain the work area to the center of the monitor.
These dynamic offsets are set at the <KomorebiConfigPlatformLink command="monitorconfig-window_based_work_area_offset_limit" text="monitor-level"/> and can be disabled individually at the <KomorebiConfigPlatformLink command="workspaceconfig-apply_window_based_work_area_offset" text="workspace-level"/>.
```json
{
"monitors": [
{
"window_based_work_area_offset_limit": 1,
"window_based_work_area_offset": {
"left": 400,
"top": 0,
"right": 800,
"bottom": 0
},
"workspaces": [
{
"name": "workspace which inherits the monitor-level window-based work area offset",
"layout": "BSP",
},
{
"name": "workspace which overrides the monitor-level window-based work area offset",
"layout": "BSP",
"apply_window_based_work_area_offset": false
},
]
}
]
}
```
The work area offset will only be applied when the number of window containers visible on the workspace is less than or equal to the `window_based_work_area_offset_limit`.
+169
View File
@@ -0,0 +1,169 @@
---
title: Rules
description: Understanding komorebi's rules system
---
import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro';
import KomorebiConfigPlatformLink from '../../../components/KomorebiConfigPlatformLink.astro';
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
<Tabs syncKey="platform">
<TabItem label="Windows">
</TabItem>
<TabItem label="macOS">
</TabItem>
</Tabs>
komorebi has a flexible rules system which aims to allow users to handle any
problematic applications they encounter via configuration rather than requiring
upstream code changes.
## Matching Rules
Applications or windows are identified using either simple or composite <KomorebiConfigPlatformLink command="matchingrule" text="matching rules" />.
Simple matching rules use a <KomorebiConfigPlatformLink command="matchingstrategy" text="matching strategy" /> against a user-provided identifier targeting an <KomorebiConfigPlatformLink command="applicationidentifier" text="application identifier" />.
<Tabs>
<TabItem label="Match on executable">
```json
{
"kind": "Exe",
"id": "Discord",
"matching_strategy": "Equals"
}
```
</TabItem>
<TabItem label="Match on title">
```json
{
"kind": "Title",
"id": "Cloudflare Dashboard",
"matching_strategy": "Contains"
}
```
</TabItem>
<TabItem label="Match on class">
```json
{
"kind": "Class",
"id": "Ableton Live Window Class",
"matching_strategy": "Equals"
}
```
</TabItem>
</Tabs>
Composite matching rules consist of multiple simple matching rules which must all evaluate to true to identify an application or window.
```json
[
{
"kind": "Exe",
"id": "zen.exe",
"matching_strategy": "Equals"
},
{
"kind": "Title",
"id": "Cloudflare Dashboard",
"matching_strategy": "Contains"
}
]
```
## Workspace Rules
<KomorebiConfigPlatformLink command="workspaceconfig-workspace_rules" text="Workspace rules" /> and <KomorebiConfigPlatformLink command="workspaceconfig-initial_workspace_rules" text="initial workspace rules" /> a are used to identify applications or windows which should be put on a specific workspace.
```json
{
"monitors": [
{
"workspaces": [
{
"name": "Chat",
"layout": "Columns",
"workspace_rules": [
{
"kind": "Exe",
"id": "Discord",
"matching_strategy": "Equals"
}
],
"initial_workspace_rules": [
{
"kind": "Exe",
"id": "Slack",
"matching_strategy": "Equals"
}
]
},
]
}
]
}
```
Workspace rules will apply all the time, effectively making it impossible to move the identified application or window to another workspace.
Initial workspace rules will only apply once when the identified application or window is first created, allowing it to be moved to another workspace later.
Workspace rules (including initial workspace rules) can be enforced in realtime using the <KomorebicPlatformLink command="enforce-workspace-rules"/> command.
## Application Handling Rules
### Ignore Rules
<KomorebiConfigPlatformLink command="ignore_rules" text="Ignore rules" /> are used to identify applications or windows which should be completely ignored by komorebi. Ignored applications cannot be targeted by any `komorebic` commands.
### Floating Applications
<KomorebiConfigPlatformLink command="floating_applications" text="Floating application rules" /> are used to identify applications or windows which should be put on the [floating layer](./usage/layers).
### Manage Rules
<KomorebiConfigPlatformLink command="manage_rules" text="Manage rules" /> are used to identify applications or windows which should be forcibly managed. This is typically a nuclear option for extremely uncooperative applications.
### Tray and Multi-Window Applications
:::note[Windows]
These rules are only applicable to komorebi for Windows
:::
<KomorebiConfigPlatformLink command="tray_and_multi_window_applications" text="Tray and multi-window application rules" /> are used to identify multi-window applications and applications which minmize to the system tray.
### Slow Application Identifier Rules
:::note[Windows]
These rules are only applicable to komorebi for Windows
:::
<KomorebiConfigPlatformLink command="slow_application_identifiers" text="Slow application identifier rules" /> are used to identify applications which are slow to send initial event notifications.
### Layered Applications
:::note[Windows]
These rules are only applicable to komorebi for Windows
:::
<KomorebiConfigPlatformLink command="layered_applications" text="Layered application rules" /> are used to identify applications have the `WS_EX_LAYERED` extended window style, but should still be managed.
### Object Name Change Applications
:::note[Windows]
These rules are only applicable to komorebi for Windows
:::
<KomorebiConfigPlatformLink command="object_name_change_applications" text="Object name change application rules" /> are used to identify applications which send `EVENT_OBJECT_NAMECHANGE` on launch. This is very rare, but includes popular applications such as Firefox (and derivatives), as well as JetBrains IDEs.
### Tabbed Applications
:::note[macOS]
These rules are only applicable to komorebi for Mac
:::
<KomorebiConfigPlatformLink command="tabbed_applications" text="Tabbed application rules" /> are used to identify applications which use native macOS tabs (Finder, Ghostty etc.) - these are identified using their application name.
### Titleless Applications
:::note[macOS]
These rules are only applicable to komorebi for Mac
:::
<KomorebiConfigPlatformLink command="titleless_applications" text="Titleless application rules" /> are used to identify applications which launch without a title - these are identified using their application name.
@@ -0,0 +1,54 @@
---
title: Themes
description: Selecting and defining themes
---
import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro';
import KomorebiConfigPlatformLink from '../../../components/KomorebiConfigPlatformLink.astro';
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
<Tabs syncKey="platform">
<TabItem label="Windows">
</TabItem>
<TabItem label="macOS">
</TabItem>
</Tabs>
komorebi comes with a number of [Base16](https://tinted-theming.github.io/tinted-gallery/) and [Catppuccin](https://catppuccin.com) themes which can be applied to [borders](/usage/borders) and the komorebi-bar.
Themes are configured by specifying a <KomorebiConfigPlatformLink command="komorebitheme" text="palette"/> (Base16 or Catppuccin), and then specifying the `name` of a theme variant.
<Tabs>
<TabItem label="Base16">
```json
{
"theme": {
"palette": "Base16",
"name": "Ashes"
}
}
```
</TabItem>
<TabItem label="Catppuccin">
```json
{
"theme": {
"palette": "Catppuccin",
"name": "Latte"
}
}
```
</TabItem>
</Tabs>
Various overrides can be set by specifying the desired <KomorebiConfigPlatformLink command="base16value" text="Base16"/> or <KomorebiConfigPlatformLink command="catppuccinvalue" text="Catppuccin"/> value:
- `theme.bar_accent`
- `theme.floating_border`
- `theme.monocle_border`
- `theme.single_border`
- `theme.stack_border`
- `theme.unfocused_border`
- `theme.unfocused_locked_border`
@@ -0,0 +1,42 @@
---
title: Wallpapers
description: Configuring monitor and workspace wallpapers
---
import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro';
import KomorebiConfigPlatformLink from '../../../components/KomorebiConfigPlatformLink.astro';
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
<Tabs syncKey="platform">
<TabItem label="Windows">
</TabItem>
<TabItem label="macOS">
</TabItem>
</Tabs>
Wallpapers can be configured at the <KomorebiConfigPlatformLink command="monitorconfig-wallpaper" text="monitor-level"/> and at the <KomorebiConfigPlatformLink command="workspaceconfig-wallpaper" text="workspace-level"/>.
```json
{
"wallpaper": {
"path": "$HOME/Pictures/wallpaper.jpg"
}
}
```
## Theme Generation
Base16 [themes](./usage/themes) can optionally <KomorebiConfigPlatformLink command="wallpaper-generate_theme" text="be generated"/> for each configured wallpaper, and overrides can be set as <KomorebiConfigPlatformLink command="themeoptions" text="theme options"/>.
```json
{
"wallpaper": {
"path": "$HOME/Pictures/wallpaper.jpg",
"generate_theme": true,
"theme_options": {
"stack_border": "Base07"
}
}
}
```
@@ -0,0 +1,88 @@
---
title: Windows
description: Manipulating windows
---
import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro';
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
<Tabs syncKey="platform">
<TabItem label="Windows">
</TabItem>
<TabItem label="macOS">
</TabItem>
</Tabs>
## Focus
Windows can be focused in the following ways.
### Relative Direction
Windows can be focused in a relative direction using the <KomorebicPlatformLink command="focus"/> command.
### Cycle Direction
Windows can be focused in a cyclic direction using the <KomorebicPlatformLink command="cycle-focus" /> command.
### Largest Tile
The window at the largest tile can be focused using the <KomorebicPlatformLink command="promote-focus" /> command.
### Eager focus
It is possible to attempt to focus the first window on any workspace matching an executable name using the <KomorebicPlatformLink command="eager-focus" /> command.
## Movement on a Workspace
Windows can be moved in the following ways.
### Relative Direction
Windows can be moved in a relative direction using the <KomorebicPlatformLink command="move"/> command.
### Cycle Direction
Windows can be moved in a cyclic direction using the <KomorebicPlatformLink command="cycle-move" /> command.
### Largest Tile
Windows can be moved to the largest tile using the <KomorebicPlatformLink command="promote-swap" /> command. This command is reversible.
## Movement Across Workspaces
The commands covering movement of windows across workspaces in komorebi come in two flavors:
- `move` - these commands move the focused window to a target workspace and then focus the target workspace
- `send` - these commands move the focused window to a target workspace while remaining on the currently focused workspace
### By Workspace Index
The focused window can be moved or sent to a workspace on the focused monitor identified by an index using the <KomorebicPlatformLink command="move-to-workspace"/> and <KomorebicPlatformLink command="send-to-workspace"/> commands respectively.
### Cycle Direction
The focused window can be moved or sent to a workspace on the focused monitor in a cyclic direction using the <KomorebicPlatformLink command="cycle-move-to-workspace"/> and <KomorebicPlatformLink command="cycle-send-to-workspace"/> commands respectively.
### By Monitor and Workspace Index
The focused window can be moved or sent to a workspace on a specific monitor identified by monitor and workspace indicies using the <KomorebicPlatformLink command="move-to-monitor-workspace"/> and <KomorebicPlatformLink command="send-to-monitor-workspace"/> commands respectively.
### By Name
The focused window can be moved or sent to a workspace in a monitor-agnostic manner by name using the <KomorebicPlatformLink command="move-to-named-workspace"/> and <KomorebicPlatformLink command="send-to-named-workspace"/> commands respectively.
### By Last Workspace
The focused window can be moved or sent to a last focused workspace on the focused monitor using the <KomorebicPlatformLink command="move-to-last-workspace"/> and <KomorebicPlatformLink command="send-to-last-workspace"/> commands respectively.
## Movement Across Monitors
### By Monitor Index
The focused window can be moved or sent the focused workspace at a monitor identified by index using the <KomorebicPlatformLink command="move-to-monitor"/> and <KomorebicPlatformLink command="send-to-monitor"/> commands respectively.
### Cycle Direction
The focused window can be moved or sent to the focused workspace of a monitor in a cyclic direction using the <KomorebicPlatformLink command="cycle-move-to-monitor"/> and <KomorebicPlatformLink command="cycle-send-to-monitor"/> commands respectively.
@@ -0,0 +1,49 @@
---
title: Workspaces
description: Configuring workspaces
---
import KomorebicPlatformLink from '../../../components/KomorebicPlatformLink.astro';
import KomorebiConfigPlatformLink from '../../../components/KomorebiConfigPlatformLink.astro';
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
<Tabs syncKey="platform">
<TabItem label="Windows">
</TabItem>
<TabItem label="macOS">
</TabItem>
</Tabs>
## Focus
Workspaces can be focused in the following ways.
### By Index
Workspaces can be focused by index on the focused monitor using the <KomorebicPlatformLink command="focus-workspace"/> command, or by a mixture of monitor index and workspace index using the <KomorebicPlatformLink command="focus-monitor-workspace"/> command.
### By Name
Workspaces can be focused in a monitor-agnostic manner by name using the <KomorebicPlatformLink command="focus-named-workspace"/> command. All of your workspaces should have unique names. If two workspaces have the same name, the first match in the window manager state will be focused.
### Cycle Direction
Workspaces can be focused in a cyclic direction using the <KomorebicPlatformLink command="cycle-workspace" /> command.
### Last Workspace
The last focused workspace on the focused monitor can be focused using the <KomorebicPlatformLink command="focus-last-workspace"/> command.
### Across Multiple Monitors
Workspaces can be focused by index across all monitors using the <KomorebicPlatformLink command="focus-workspaces"/> command. This will focus the same workspace index on all monitors simultaneously, giving the feeling of a workspaces which span all monitors.
## Movement
Workspaces can be moved to other monitors in the following ways.
### By Focus and Index
The focused workspace can be moved to a monitor identified by an index using the <KomorebicPlatformLink command="move-workspace-to-monitor"/> command.
@@ -0,0 +1,19 @@
```
Adjust container padding on the focused workspace
Usage: adjust-container-padding <SIZING> <ADJUSTMENT>
Arguments:
<SIZING>
Possible values:
- increase: Increase
- decrease: Decrease
<ADJUSTMENT>
Pixels to adjust by as an integer
Options:
-h, --help
Print help (see a summary with '-h')
```
@@ -0,0 +1,19 @@
```
Adjust workspace padding on the focused workspace
Usage: adjust-workspace-padding <SIZING> <ADJUSTMENT>
Arguments:
<SIZING>
Possible values:
- increase: Increase
- decrease: Decrease
<ADJUSTMENT>
Pixels to adjust by as an integer
Options:
-h, --help
Print help (see a summary with '-h')
```
@@ -0,0 +1,19 @@
```
Set the duration for movement animations in ms
Usage: animation-duration [OPTIONS] <DURATION>
Arguments:
<DURATION>
Desired animation durations in ms
Options:
-a, --animation-type <ANIMATION_TYPE>
Animation type to apply the duration to. If not specified, sets global duration
[possible values: movement]
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Set the frames per second for movement animations
Usage: animation-fps <FPS>
Arguments:
<FPS>
Desired animation frames per second
Options:
-h, --help
Print help
```
@@ -0,0 +1,53 @@
```
Set the ease function for movement animations
Usage: animation-style [OPTIONS]
Options:
-s, --style <STYLE>
Desired ease function for animation
Possible values:
- linear: Linear
- ease-in-sine: Ease in sine
- ease-out-sine: Ease out sine
- ease-in-out-sine: Ease in out sine
- ease-in-quad: Ease in quad
- ease-out-quad: Ease out quad
- ease-in-out-quad: Ease in out quad
- ease-in-cubic: Ease in cubic
- ease-out-cubic: Ease out cubic
- ease-in-out-cubic: Ease in out cubic
- ease-in-quart: Ease in quart
- ease-out-quart: Ease out quart
- ease-in-out-quart: Ease in out quart
- ease-in-quint: Ease in quint
- ease-out-quint: Ease out quint
- ease-in-out-quint: Ease in out quint
- ease-in-expo: Ease in expo
- ease-out-expo: Ease out expo
- ease-in-out-expo: Ease in out expo
- ease-in-circ: Ease in circ
- ease-out-circ: Ease out circ
- ease-in-out-circ: Ease in out circ
- ease-in-back: Ease in back
- ease-out-back: Ease out back
- ease-in-out-back: Ease in out back
- ease-in-elastic: Ease in elastic
- ease-out-elastic: Ease out elastic
- ease-in-out-elastic: Ease in out elastic
- ease-in-bounce: Ease in bounce
- ease-out-bounce: Ease out bounce
- ease-in-out-bounce: Ease in out bounce
[default: linear]
-a, --animation-type <ANIMATION_TYPE>
Animation type to apply the style to. If not specified, sets global style
[possible values: movement]
-h, --help
Print help (see a summary with '-h')
```
+19
View File
@@ -0,0 +1,19 @@
```
Enable or disable movement animations
Usage: animation [OPTIONS] <BOOLEAN_STATE>
Arguments:
<BOOLEAN_STATE>
[possible values: enable, disable]
Options:
-a, --animation-type <ANIMATION_TYPE>
Animation type to apply the state to. If not specified, sets global state
[possible values: movement]
-h, --help
Print help
```
@@ -0,0 +1,10 @@
```
Generate a JSON Schema for applications.json
Usage: application-specific-configuration-schema
Options:
-h, --help
Print help
```
@@ -0,0 +1,24 @@
```
Set the colour for a window border kind
Usage: border-colour [OPTIONS] <R> <G> <B>
Arguments:
<R>
Red
<G>
Green
<B>
Blue
Options:
-w, --window-kind <WINDOW_KIND>
[default: single]
[possible values: single, stack, monocle, unfocused, unfocused-locked, floating]
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Set the border offset
Usage: border-offset <OFFSET>
Arguments:
<OFFSET>
Desired offset of the window border
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Set the border width
Usage: border-width <WIDTH>
Arguments:
<WIDTH>
Desired width of the window border
Options:
-h, --help
Print help
```
+14
View File
@@ -0,0 +1,14 @@
```
Enable or disable borders
Usage: border <BOOLEAN_STATE>
Arguments:
<BOOLEAN_STATE>
[possible values: enable, disable]
Options:
-h, --help
Print help
```
@@ -0,0 +1,10 @@
```
Cancel a workspace preselect set by the preselect-direction command, if one exists
Usage: cancel-preselect
Options:
-h, --help
Print help
```
@@ -0,0 +1,23 @@
```
Set the layout on the focused workspace
Usage: change-layout <DEFAULT_LAYOUT>
Arguments:
<DEFAULT_LAYOUT>
Possible values:
- bsp: BSP Layout
- columns: Columns Layout
- rows: Rows Layout
- vertical-stack: Vertical Stack Layout
- horizontal-stack: Horizontal Stack Layout
- ultrawide-vertical-stack: Ultrawide Vertical Stack Layout
- grid: Grid Layout
- right-main-vertical-stack: Right Main Vertical Stack Layout
- scrolling: Scrolling Layout
Options:
-h, --help
Print help (see a summary with '-h')
```
@@ -0,0 +1,10 @@
```
Remove all application association rules for all workspaces
Usage: clear-all-workspace-rules
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Clear all dynamic layout rules for the specified workspace
Usage: clear-named-workspace-layout-rules <WORKSPACE>
Arguments:
<WORKSPACE>
Target workspace name
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Remove all application association rules for a named workspace
Usage: clear-named-workspace-rules <WORKSPACE>
Arguments:
<WORKSPACE>
Name of a workspace
Options:
-h, --help
Print help
```
@@ -0,0 +1,10 @@
```
Clear all session float rules
Usage: clear-session-float-rules
Options:
-h, --help
Print help
```
@@ -0,0 +1,17 @@
```
Clear all dynamic layout rules for the specified workspace
Usage: clear-workspace-layout-rules <MONITOR> <WORKSPACE>
Arguments:
<MONITOR>
Monitor index (zero-indexed)
<WORKSPACE>
Workspace index on the specified monitor (zero-indexed)
Options:
-h, --help
Print help
```
@@ -0,0 +1,17 @@
```
Remove all application association rules for a workspace by monitor and workspace index
Usage: clear-workspace-rules <MONITOR> <WORKSPACE>
Arguments:
<MONITOR>
Monitor index (zero-indexed)
<WORKSPACE>
Workspace index on the specified monitor (zero-indexed)
Options:
-h, --help
Print help
```
@@ -0,0 +1,10 @@
```
Close the focused workspace (must be empty and unnamed)
Usage: close-workspace
Options:
-h, --help
Print help
```
+10
View File
@@ -0,0 +1,10 @@
```
Close the focused window
Usage: close
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Generate komorebic CLI completions for the target shell
Usage: completions <SHELL>
Arguments:
<SHELL>
[possible values: bash, elvish, fish, powershell, zsh]
Options:
-h, --help
Print help
```
@@ -0,0 +1,10 @@
```
Show the path to komorebi.json
Usage: configuration
Options:
-h, --help
Print help
```
@@ -0,0 +1,20 @@
```
Set the container padding for the specified workspace
Usage: container-padding <MONITOR> <WORKSPACE> <SIZE>
Arguments:
<MONITOR>
Monitor index (zero-indexed)
<WORKSPACE>
Workspace index on the specified monitor (zero-indexed)
<SIZE>
Pixels to pad with as an integer
Options:
-h, --help
Print help
```
@@ -0,0 +1,17 @@
```
Set the behaviour when moving windows across monitor boundaries
Usage: cross-monitor-move-behaviour <MOVE_BEHAVIOUR>
Arguments:
<MOVE_BEHAVIOUR>
Possible values:
- swap: Swap the window container with the window container at the edge of the adjacent monitor
- insert: Insert the window container into the focused workspace on the adjacent monitor
- no-op: Do nothing if trying to move a window container in the direction of an adjacent monitor
Options:
-h, --help
Print help (see a summary with '-h')
```
@@ -0,0 +1,14 @@
```
Focus the next empty workspace in the given cycle direction (if one exists)
Usage: cycle-empty-workspace <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Change focus to the window in the specified cycle direction
Usage: cycle-focus <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Cycle between available layouts
Usage: cycle-layout <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Focus the monitor in the given cycle direction
Usage: cycle-monitor <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Move the focused window to the monitor in the given cycle direction
Usage: cycle-move-to-monitor <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Move the focused window to the workspace in the given cycle direction
Usage: cycle-move-to-workspace <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Move the focused workspace monitor in the given cycle direction
Usage: cycle-move-workspace-to-monitor <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Move the focused window in the specified cycle direction
Usage: cycle-move <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Send the focused window to the monitor in the given cycle direction
Usage: cycle-send-to-monitor <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Send the focused window to the workspace in the given cycle direction
Usage: cycle-send-to-workspace <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Cycle the index of the focused window in the focused stack in the specified cycle direction
Usage: cycle-stack-index <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Cycle the focused stack in the specified cycle direction
Usage: cycle-stack <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Focus the workspace in the given cycle direction
Usage: cycle-workspace <CYCLE_DIRECTION>
Arguments:
<CYCLE_DIRECTION>
[possible values: previous, next]
Options:
-h, --help
Print help
```
@@ -0,0 +1,10 @@
```
Show the path to komorebi's data directory in $HOME/Library/Application Support
Usage: data-directory
Options:
-h, --help
Print help
```
@@ -0,0 +1,10 @@
```
Unloads and deletes the com.lgug2z.komorebi.plist file in $HOME/Library/LaunchAgents
Usage: disable-autostart
Options:
-h, --help
Print help
```
@@ -0,0 +1,17 @@
```
Set the display index preference for a monitor identified using its display name
Usage: display-index-preference <INDEX_PREFERENCE> <DISPLAY>
Arguments:
<INDEX_PREFERENCE>
Preferred monitor index (zero-indexed)
<DISPLAY>
Display name as identified in komorebic state
Options:
-h, --help
Print help
```
@@ -0,0 +1,14 @@
```
Focus the first managed window matching the given executable
Usage: eager-focus <EXE>
Arguments:
<EXE>
Case-sensitive exe identifier
Options:
-h, --help
Print help
```
@@ -0,0 +1,16 @@
```
Generates and loads the com.lgug2z.komorebi.plist file in $HOME/Library/LaunchAgents
Usage: enable-autostart [OPTIONS]
Options:
-c, --config <CONFIG>
Path to a static configuration JSON file
--bar
Enable autostart of komorebi-bar
-h, --help
Print help
```
@@ -0,0 +1,10 @@
```
Enforce all workspace rules, including initial workspace rules that have already been applied
Usage: enforce-workspace-rules
Options:
-h, --help
Print help
```
@@ -0,0 +1,17 @@
```
Create these many named workspaces for the specified monitor
Usage: ensure-named-workspaces <MONITOR> [NAMES]...
Arguments:
<MONITOR>
Monitor index (zero-indexed)
[NAMES]...
Names of desired workspaces
Options:
-h, --help
Print help
```
@@ -0,0 +1,17 @@
```
Create at least this many workspaces for the specified monitor
Usage: ensure-workspaces <MONITOR> <WORKSPACE_COUNT>
Arguments:
<MONITOR>
Monitor index (zero-indexed)
<WORKSPACE_COUNT>
Number of desired workspaces
Options:
-h, --help
Print help
```
@@ -0,0 +1,10 @@
```
Fetch the latest version of applications.json from komorebi-application-specific-configuration
Usage: fetch-app-specific-configuration
Options:
-h, --help
Print help
```
@@ -0,0 +1,17 @@
```
Flip the layout on the focused workspace
Usage: flip-layout <AXIS>
Arguments:
<AXIS>
Possible values:
- horizontal: Horizontal axis
- vertical: Vertical axis
- horizontal-and-vertical: Both horizontal and vertical axes
Options:
-h, --help
Print help (see a summary with '-h')
```
@@ -0,0 +1,10 @@
```
Focus the last focused workspace on the focused monitor
Usage: focus-last-workspace
Options:
-h, --help
Print help
```
@@ -0,0 +1,10 @@
```
Focus the monitor at the current cursor location
Usage: focus-monitor-at-cursor
Options:
-h, --help
Print help
```
@@ -0,0 +1,17 @@
```
Focus the specified workspace on the target monitor
Usage: focus-monitor-workspace <TARGET_MONITOR> <TARGET_WORKSPACE>
Arguments:
<TARGET_MONITOR>
Target monitor index (zero-indexed)
<TARGET_WORKSPACE>
Workspace index on the target monitor (zero-indexed)
Options:
-h, --help
Print help
```
Loaded 100 of 378 files, more files were not shown because too many files have changed in this diff. Show more