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:
- Config directory exists
- All configuration files are valid TOML
- All keybinding key names resolve to valid key codes
- Daemon status (running, stopped, or stale)
- 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:
| Column | Description |
|---|---|
| HWND | Window handle in hex |
| Managed | Whether the window is tiled |
| Monitor | Which monitor the window is on |
| Title | Window title |
| Class | Window class name |
| Position | X, Y coordinates |
| Size | Width and height |
| Border Offset | Invisible frame compensation values |
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).