Mosaico

A cross-platform tiling window manager, written in Rust.

Mosaico automatically arranges your windows into a non-overlapping tiled layout using a Binary Space Partitioning (BSP) algorithm. It runs as a lightweight background daemon and is controlled entirely from the command line or via global keyboard shortcuts.

Features

• Automatic tiling – windows are arranged in a BSP layout the moment they open, close, or are moved between monitors.
• Vim-style navigation – focus and move windows with Alt + H/J/K/L.
• Workspaces – up to 8 independent workspaces per monitor.
• Multi-monitor – each monitor is managed independently with cross-monitor navigation.
• Focus borders – colored overlay border around the focused window.
• Monocle mode – full-screen single-window mode per monitor.
• Status bar – configurable per-monitor bar with workspace indicators, clock, CPU, RAM, and more.
• Catppuccin theming – built-in theme system with four flavors.
• Hot-reload – configuration changes are applied without restarting.
• Window rules – exclude specific applications from tiling.

Quick Start

# Install on Windows
irm https://raw.githubusercontent.com/jmelosegui/mosaico/main/docs/install.ps1 | iex

# Create default config files
mosaico init

# Start the window manager
mosaico start

See Installation for more options or Getting Started for a walkthrough.

License

Mosaico is released under the MIT License.

Installation

Windows

Run the following command in PowerShell to download and install the latest release:

irm https://raw.githubusercontent.com/jmelosegui/mosaico/main/docs/install.ps1 | iex

The installer downloads the latest release from GitHub and places the binary in %LOCALAPPDATA%\mosaico. It also adds that directory to your user PATH so you can run mosaico from any terminal.

From Source

If you have the Rust toolchain installed, you can build and install directly:

cargo install --path .

Or build a release binary without installing:

cargo build --release

The binary will be at target/release/mosaico.exe.

Verifying the Installation

After installing, verify that Mosaico is available:

mosaico --version

You should see the version number printed to the terminal.

Getting Started

This guide walks you through your first session with Mosaico.

1. Generate Configuration Files

Create the default configuration files in ~/.config/mosaico/:

mosaico init

This generates the following files:

Existing files are never overwritten, so it is safe to run init again.

2. Start the Window Manager

mosaico start

Mosaico launches a background daemon that immediately tiles all visible windows on your desktop. You will see a startup banner with your config directory, the daemon PID, and a helpful tip.

3. Navigate with Keyboard Shortcuts

The default keybindings use vim-style motions:

4. Check the Status

mosaico status

Reports whether the daemon is running and its PID.

5. Run the Doctor

mosaico doctor

Performs a health check on your configuration files, daemon status, and monitor setup. Any issues are reported with colored status tags.

6. Stop the Window Manager

mosaico stop

All windows are restored to their original state before the daemon exits.

Next Steps

• CLI Commands – full command reference
• Configuration – customize layout, borders, and more
• Keyboard Bindings – change or add shortcuts
• Workspaces – learn about multi-workspace support

CLI Commands

All interactions with Mosaico go through the command-line interface.

mosaico init

Creates default configuration files in ~/.config/mosaico/:

• config.toml – layout, border, theme, and logging settings
• keybindings.toml – keyboard shortcuts
• rules.toml – community window rules (auto-updated on daemon startup)
• user-rules.toml – personal rule overrides
• bar.toml – status bar settings

Files that already exist are skipped to preserve your customizations. On first run, you are prompted to enable automatic startup.

mosaico start

Launches the daemon as a detached background process. On success, a startup banner is printed showing the config directory, PID, and a usage tip. If a newer release is available on GitHub, an update notice is shown.

If the daemon is already running, the command reports the existing state instead of starting a second instance.

mosaico stop

Sends a stop command to the running daemon. All windows are restored to their original positions before the daemon exits. If the daemon is unresponsive, a fallback mechanism terminates the process directly.

mosaico status

Reports whether the daemon is running, along with its PID. Detects and cleans up stale PID files from crashed sessions.

mosaico doctor

Runs a comprehensive health check and prints colored status tags for each item:

Checks performed:

1. Config directory exists (creates it if missing)
2. config.toml syntax validation
3. Theme flavor validation
4. keybindings.toml syntax validation
5. Key names resolve to valid key codes
6. rules.toml syntax validation
7. Community rules cache age
8. user-rules.toml syntax validation
9. bar.toml syntax validation
10. Autostart status
11. Daemon status (IPC pipe, PID file, process liveness)
12. Monitor enumeration and dimensions

mosaico autostart

Manages automatic startup when Windows boots.

mosaico autostart enable    # Register to start on logon
mosaico autostart disable   # Remove the startup entry
mosaico autostart status    # Show current autostart state

This writes a value under the HKEY_CURRENT_USER registry Run key, so no administrator rights are needed.

On first run, mosaico init also prompts to enable autostart.

mosaico update

Checks GitHub for a newer release and installs it automatically. If the daemon is running, it is stopped before the update and restarted afterward.

mosaico update          # Update to the latest release
mosaico update --force  # Reinstall even if already on the latest version

The --force flag is useful for recovering a corrupted binary.

mosaico action <verb> [direction]

Sends a tiling action to the running daemon. Available actions:

mosaico action focus left|right|up|down
mosaico action move left|right|up|down
mosaico action retile
mosaico action toggle-monocle
mosaico action close-focused
mosaico action goto-workspace <1-8>
mosaico action send-to-workspace <1-8>

These are the same actions triggered by keyboard shortcuts, useful for scripting or integration with other tools.

mosaico debug list

Displays a formatted table of all visible windows showing:

• HWND (hex)
• Managed status
• Monitor number
• Title and class name
• Position and dimensions
• Border offset

mosaico debug events

Streams real-time window events to stdout. Press Ctrl+C to stop. Useful for understanding how Mosaico reacts to window changes.

mosaico debug move <hwnd> <x> <y> <width> <height>

Moves a specific window to exact pixel coordinates. The HWND can be provided in decimal or 0x hex format. Useful for testing window positioning.

Configuration

Mosaico uses TOML configuration files stored in ~/.config/mosaico/. All settings have sensible defaults, so configuration files are entirely optional.

Run mosaico init to generate fully-commented template files.

Configuration Files

config.toml

Controls layout, borders, logging, and theme:

[layout]
default = "bsp"  # Default layout algorithm: "bsp", "vertical-stack", "three-column"
gap = 8          # Pixel gap between windows (0-200)
ratio = 0.5      # BSP split ratio (0.1-0.9)
hiding = "cloak" # How windows hide on workspace switch: "cloak", "hide", "minimize"

[layout.workspaces]
1 = "three-column"    # Override layout for workspace 1
3 = "vertical-stack"  # Override layout for workspace 3
# Workspaces without an entry use the default layout

[borders]
width = 4              # Border thickness in pixels (0-32)
corner_style = "small" # "square", "small", or "round"
focused = "#00b4d8"    # Hex color for focused window
monocle = "#2d6a4f"    # Hex color for monocle mode

[theme]
flavor = "mocha"   # Catppuccin flavor: latte, frappe, macchiato, mocha

[logging]
enabled = false    # Enable file logging
level = "info"     # Log level: debug, info, warn, error
max_file_mb = 10   # Max log file size before rotation

keybindings.toml

Maps key combinations to actions. See Keyboard Bindings for the full reference.

[[keybinding]]
action = "focus-down"
key = "J"
modifiers = ["alt"]

bar.toml

Configures the status bar. See Status Bar for details.

enabled = true
height = 28
monitor = "all"      # "all", "primary", or 0-based index

[colors]
background = "base"      # Named Catppuccin color
foreground = "text"
accent = "blue"

[[left]]
type = "workspaces"

[[center]]
type = "clock"
format = "%H:%M"

[[right]]
type = "cpu"

rules.toml and user-rules.toml

Window rules control which applications are tiled. Community rules are downloaded automatically to rules.toml on daemon startup. Add personal overrides in user-rules.toml (user rules take priority).

See Window Rules for details.

# user-rules.toml — your personal overrides
[[rule]]
match_title = "My Private Tool"
manage = false

Partial Files

All configuration fields have defaults. You only need to include the settings you want to change. A file containing only:

[layout]
gap = 12

will use defaults for everything else.

Validation

Out-of-range values are automatically clamped to safe boundaries rather than rejected:

Hot-Reload

Changes to config.toml, user-rules.toml, and bar.toml are automatically detected and applied while the daemon is running (polled every 2 seconds).

• config.toml – layout gap/ratio, hiding behaviour, border settings, and theme are reloaded. Windows are retiled immediately. Hiding changes take effect on the next workspace switch.
• user-rules.toml – both rule sets are re-merged and existing windows are re-evaluated against the new rules.
• bar.toml – the status bar is recreated with updated settings and colors.
• rules.toml – community rules, updated only on daemon startup.
• keybindings.toml – not hot-reloaded. Changes require a daemon restart (mosaico stop && mosaico start).

Only valid configurations are applied. If a file change introduces a parse error, the current configuration is kept and a warning is logged.

Keyboard Bindings

Mosaico registers global system hotkeys that work regardless of which application has focus. Keybindings are configured in ~/.config/mosaico/keybindings.toml.

Default Keybindings

The defaults use vim-style spatial navigation (H=left, J=down, K=up, L=right):

Configuration Format

Each binding is a [[keybinding]] entry with three fields:

[[keybinding]]
action = "focus-left"
key = "H"
modifiers = ["alt"]

[[keybinding]]
action = "move-left"
key = "H"
modifiers = ["alt", "shift"]

Actions

Modifiers

Supported Keys

Unknown key names are skipped with a log message.

Reloading

Keybinding changes are not hot-reloaded. You must restart the daemon for changes to take effect:

mosaico stop && mosaico start

Window Rules

Window rules control which applications Mosaico manages. Rules are split into two files:

Both files live in ~/.config/mosaico/.

How It Works

When the daemon starts, it downloads the latest community rules from the mosaico-rules repository and saves them to rules.toml. Your personal rules in user-rules.toml are never touched.

At runtime, both files are merged: user rules are evaluated first, so they take priority over community defaults. The first matching rule wins.

Rule Format

Each rule is a [[rule]] entry:

[[rule]]
match_class = "ApplicationFrameWindow"
manage = false

[[rule]]
match_title = "Calculator"
manage = false

[[rule]]
match_class = "Chrome_WidgetWin_1"
match_title = "Picture-in-Picture"
manage = false

Rule Fields

Matching Behavior

• Class match: case-insensitive exact match against the window class name.
• Title match: case-insensitive substring match against the window title.
• If a rule specifies both match_class and match_title, both must match.
• If a rule specifies neither, it matches everything.

Evaluation Order

Rules are evaluated in order. User rules (user-rules.toml) come first, followed by community rules (rules.toml). The first matching rule wins. If no rule matches a window, it is managed by default.

This means you can override any community rule by adding a rule in user-rules.toml. For example, to force-tile a window that community rules exclude:

# user-rules.toml
[[rule]]
match_class = "Chrome_WidgetWin_1"
manage = true

Community Rules

Community rules are maintained at github.com/jmelosegui/mosaico-rules. They cover common exclusions like UWP apps, GPU overlays, system dialogs, and VPN clients.

If you find a window that should be excluded for all users, consider contributing the rule upstream instead of keeping it in user-rules.toml.

Hot-Reload

Changes to user-rules.toml are automatically detected and applied while the daemon is running. When the file changes, both rule sets are re-merged and existing windows are re-evaluated against the new rules.

Community rules (rules.toml) are only updated on daemon startup.

Finding Window Class Names

Use the debug list command to see the class names of all visible windows:

mosaico debug list

The output includes the class name for each window, which you can use in your rules.

Status Bar

Mosaico includes a configurable status bar that sits at the top of each monitor. It is configured in ~/.config/mosaico/bar.toml.

Configuration

enabled = true
height = 28
monitor = "all"      # "all", "primary", or 0-based index

[colors]
background = "base"      # Named Catppuccin color or hex
foreground = "text"
accent = "blue"

[[left]]
type = "workspaces"

[[center]]
type = "clock"
format = "%H:%M"

[[right]]
type = "cpu"

General Settings

The monitor field accepts:

• "all" – show on every monitor
• "primary" – show only on the primary monitor
• A number (e.g. 0, 1) – show on a specific monitor by index

Colors

Colors can be specified as hex values ("#1e1e2e") or as named Catppuccin colors ("base", "text", "blue", etc.). See Theming for the full list of named colors.

Widgets

Widgets are placed in [[left]], [[center]], or [[right]] arrays.

The active_window widget displays the application icon of the currently focused window. It extracts the icon from the running process and renders it as a bitmap in the bar. When no window is focused or the icon cannot be determined, the widget is hidden automatically.

The media widget shows the currently playing track (“Artist - Title”) using the Windows media transport controls API (GSMTC). It works with Spotify, browser media (YouTube, SoundCloud, etc.), VLC, and any app that integrates with Windows media controls. When nothing is playing, the widget is hidden automatically. Long titles are truncated to max_length characters (default 40) with an ellipsis. Some third-party media apps may not register with GSMTC and will not be detected.

[[right]]
type = "media"
icon = "\uF001"       # music note icon
max_length = 40       # truncate long titles

Example: Full Bar

[[left]]
type = "workspaces"

[[left]]
type = "active_window"

[[left]]
type = "layout"

[[center]]
type = "clock"
format = "%H:%M"

[[right]]
type = "media"
icon = "\uF001"
max_length = 40

[[right]]
type = "cpu"

[[right]]
type = "ram"

[[right]]
type = "date"
format = "%a %d %b"

Work Area

The bar reserves space at the top of the monitor. The tiling layout automatically accounts for the bar height so windows do not overlap it.

Hot-Reload

Changes to bar.toml are automatically applied while the daemon is running. The bar is recreated with the new settings and all monitors are retiled.

Theming

Mosaico includes a built-in theme system based on the Catppuccin color palette. Themes provide a consistent color scheme across focus borders, monocle borders, and the status bar.

Configuration

Set the theme flavor in config.toml:

[theme]
flavor = "mocha"   # latte, frappe, macchiato, mocha

Available Flavors

Named Colors

When a theme is active, you can use named colors anywhere a color value is expected (borders, bar colors). The following 14 accent colors are available:

Additional named colors for surfaces and text:

Color Resolution

Colors are resolved in the following order:

1. Hex value ("#1e1e2e") – used as-is
2. Named color ("blue") – looked up in the active theme palette
3. Empty string – falls back to the default for that setting

Existing hex color values in your configuration continue to work unchanged after enabling a theme. Named colors are optional.

Examples

Using named colors in bar.toml:

[colors]
background = "base"
foreground = "text"
accent = "blue"

Using named colors for borders in config.toml:

[borders]
focused = "blue"
monocle = "green"

Hot-Reload

Theme changes in config.toml are hot-reloaded. When the flavor changes, all named colors are re-resolved against the new palette and the bar is updated without restarting.

Tiling & Layouts

Mosaico automatically arranges windows on each monitor using a tiling layout algorithm. Three layouts are available out of the box: BSP, VerticalStack, and ThreeColumn.

Layout Algorithms

BSP (Binary Space Partitioning)

The default layout. The algorithm recursively divides the available screen area:

1. One window – fills the entire work area (minus gaps).
2. Two or more windows – the area is split in half:
   • Even depth: horizontal split (side by side)
   • Odd depth: vertical split (stacked)
3. The first window gets the primary partition (controlled by the ratio setting).
4. Remaining windows are recursively laid out in the second partition.

This produces a balanced, grid-like arrangement where each new window gets its own tile.

+-------+-------+
|       |   2   |
|   1   +---+---+
|       | 3 | 4 |
+-------+---+---+

VerticalStack

A classic master/stack layout. The first window occupies a large pane on the left (the “master”), and all remaining windows are stacked vertically on the right.

+-----------+-----------+
|           |     2     |
|     1     +-----------+
| (master)  |     3     |
+-----------+-----------+

This layout works well when you have one main window you want to keep visible (editor, browser) while referencing several smaller ones.

ThreeColumn

A centered-master layout. The first window sits in the center column, and additional windows alternate between stacks on the left and right sides.

+------+-----------+------+
|  2   |           |  3   |
+------+     1     +------+
|  4   | (master)  |  5   |
+------+-----------+------+

With only two windows it behaves like a simple left/right split. Once a third window is added, the center master column appears and the side stacks begin filling up.

Cycling Layouts

Press Alt + N to cycle through layouts on the focused workspace:

BSP -> VerticalStack -> ThreeColumn -> BSP -> …

You can also run:

mosaico action cycle-layout

The layout change takes effect immediately and all windows are retiled.

Configuration

Layout settings are in config.toml:

[layout]
gap = 8               # Pixel gap between windows (0-200)
ratio = 0.5           # Split ratio for the primary partition (0.1-0.9)
default = "bsp"       # Default layout for all workspaces

• gap – the pixel spacing between windows and around the edges of the screen. Set to 0 for no gaps.
• ratio – controls how much space the first window in each split receives. 0.5 means equal halves; 0.6 gives 60% to the primary window.
• default – the layout algorithm used for any workspace that does not have an explicit override. Accepted values: "bsp", "vertical-stack", "three-column".

Per-Workspace Layout

You can assign a specific layout to individual workspaces using the [layout.workspaces] section. Workspace numbers range from 1 to 8.

[layout]
default = "bsp"

[layout.workspaces]
1 = "three-column"     # Workspace 1 always uses ThreeColumn
3 = "vertical-stack"   # Workspace 3 always uses VerticalStack

Workspaces without an entry in this table use the default layout. You can still cycle layouts at runtime with Alt + N – the per-workspace config only controls the initial layout when the daemon starts.

Monocle Mode

A per-monitor toggle that makes the focused window fill the entire work area. Other windows remain in the workspace but are not repositioned.

• Toggle with Alt + T or mosaico action toggle-monocle
• The focus border color changes to the configured monocle color
• Each monitor has its own independent monocle state

Retiling

Mosaico automatically retiles when windows are opened, closed, minimized, restored, or moved between monitors. You can also manually retile at any time:

• Press Alt + Shift + R
• Or run mosaico action retile

Window Management

Mosaico tiles a window if it meets all of the following criteria:

1. The window is visible
2. The window has a title bar (WS_CAPTION style)
3. The window is not a tool window
4. The window passes your window rules

Layout Changes Are Hot-Reloaded

Changes to gap, ratio, default, and workspaces in config.toml are automatically applied while the daemon is running. All windows are retiled immediately with the new settings.

Workspaces

Mosaico supports up to 8 independent workspaces per monitor. Each workspace maintains its own set of tiled windows.

Switching Workspaces

Or via the CLI:

mosaico action goto-workspace 3
mosaico action send-to-workspace 5

Behavior

Switching (goto-workspace)

When you switch to a different workspace:

1. All windows on the current workspace are hidden using the configured hiding strategy
2. All windows on the target workspace are shown
3. The layout is reapplied
4. Focus is set to the first window

If you are already on the target workspace, nothing happens.

Sending (send-to-workspace)

When you send a window to another workspace:

1. The focused window is removed from the current workspace
2. It is added to the target workspace
3. The window is hidden (it is now on a non-active workspace)
4. The current workspace is retiled
5. Focus moves to the next window

Hiding Behaviour

The hiding setting in [layout] controls how windows are hidden during workspace switches:

[layout]
hiding = "cloak"   # "cloak", "hide", or "minimize"

Cloak is the recommended default. Windows become invisible but keep their taskbar icons, so you can still see all running apps. Clicking a cloaked window’s taskbar icon automatically switches to its workspace.

Per-Monitor Workspaces

Each monitor has its own independent set of 8 workspaces. Switching workspaces on one monitor does not affect other monitors.

Status Bar Integration

If the status bar is enabled with a workspaces widget, it displays pill-shaped indicators showing which workspace is active and which workspaces contain windows.

Multi-Monitor

Mosaico manages each monitor independently with its own workspaces, layout, and monocle state. Windows can be navigated and moved across monitors seamlessly.

Monitor Detection

Monitors are automatically enumerated and sorted left-to-right by their x-coordinate. Each monitor’s work area excludes the Windows taskbar and the Mosaico status bar (if enabled).

Cross-Monitor Navigation

Focus navigation with Alt + H/L (left/right) can cross monitor boundaries. When there is no window in the requested direction on the current monitor, focus moves to the nearest window on the adjacent monitor.

Up/Down navigation (Alt + J/K) stays within the current monitor.

Moving Windows Across Monitors

Move actions with Alt + Shift + H/L transfer windows between monitors:

• Moving right – the window is placed at the leftmost position in the target monitor’s BSP layout.
• Moving left – the window is placed at the rightmost position.

Both the source and target monitors are retiled after the move.

Up/Down move actions (Alt + Shift + J/K) swap windows within the same monitor.

Manual Dragging

If you manually drag a window to a different monitor, Mosaico detects the monitor change and reassigns the window automatically. Both monitors are retiled.

DPI Awareness

Mosaico uses per-monitor DPI awareness (V2) to ensure accurate pixel positioning on mixed-DPI multi-monitor setups. This is handled automatically and requires no configuration.

Focus Borders

Mosaico draws a colored border overlay around the currently focused window, making it easy to identify which window has focus.

Configuration

Border settings are in config.toml:

[borders]
width = 4              # Border thickness in pixels (0-32)
corner_style = "small" # "square", "small", or "round"
focused = "#00b4d8"    # Color for focused window
monocle = "#2d6a4f"    # Color for monocle mode

• width – thickness of the border in pixels. Set to 0 to disable the focus border entirely.

• corner_style – controls both the border overlay shape and the DWM corner preference for tiled windows (Windows 11 only; ignored on Windows 10).

  Value	Border overlay	DWM (Windows 11)
  "square"	Sharp corners (0 px)	DONOTROUND
  "small"	Subtle rounding (8 px)	ROUNDSMALL (~4 px)
  "round"	Standard rounding (16 px)	ROUND (~8 px)

• focused – the border color during normal tiling. Accepts hex colors or named Catppuccin colors (see Theming).

• monocle – the border color when monocle mode is active.

Behavior

• The border automatically follows focus as you navigate between windows
• It is a click-through overlay that does not interfere with your interaction with the focused window
• The border sits on top of all windows (topmost)
• It is excluded from tiling (it is invisible to the tiling manager)

Using Named Colors

With a theme active, you can use named colors:

[borders]
focused = "blue"
monocle = "green"

Hot-Reload

Border settings are hot-reloaded. Changes to width, corner_style, focused, and monocle colors take effect immediately.

Logging

Mosaico includes a built-in file logger with automatic rotation. Logging is disabled by default.

Configuration

Enable logging in config.toml:

[logging]
enabled = true
level = "info"        # debug, info, warn, error
max_file_mb = 10      # Max file size before rotation

Log Levels

Log Location

Logs are written to:

~/.config/mosaico/logs/mosaico.log

Rotation

When the log file exceeds max_file_mb, it is rotated:

• The current file is renamed to mosaico.log.1
• A new mosaico.log is created
• Only one backup file is kept

When to Enable Logging

Logging is most useful when:

• Debugging why a window is not being tiled
• Investigating unexpected behavior
• Reporting issues on GitHub

For general use, logging can remain disabled to avoid unnecessary disk writes.

Debugging

Mosaico provides several tools for inspecting and troubleshooting the window manager.

mosaico doctor

The doctor command performs a comprehensive health check:

mosaico doctor

It checks:

1. Config directory exists
2. All configuration files are valid TOML
3. All keybinding key names resolve to valid key codes
4. Daemon status (running, stopped, or stale)
5. Monitor enumeration and dimensions

Issues are reported with colored tags: [ok], [warn], [fail], or [fixed].

mosaico debug list

Lists all visible windows on the desktop:

mosaico debug list

The output is a formatted table showing:

This is useful for finding window class names when writing window rules.

mosaico debug events

Streams window events in real time:

mosaico debug events

Shows events like window creation, destruction, focus changes, moves, minimize/restore, and title changes. Press Ctrl+C to stop.

This is useful for understanding how Mosaico reacts to window changes and diagnosing timing issues.

mosaico debug move

Moves a specific window to exact coordinates:

mosaico debug move 0x1A2B3C 100 200 800 600

Arguments: <hwnd> <x> <y> <width> <height>. The HWND can be in decimal or 0x hex format (use debug list to find it).