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:
| File | Purpose |
|---|---|
config.toml | Layout, border, theme, and logging settings |
keybindings.toml | Keyboard shortcut mappings |
rules.toml | Community rules (auto-updated on daemon startup) |
user-rules.toml | Personal rule overrides (never overwritten) |
bar.toml | Status bar settings |
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:
| Shortcut | Action |
|---|---|
Alt + H | Focus the window to the left |
Alt + J | Focus the window below |
Alt + K | Focus the window above |
Alt + L | Focus the window to the right |
Alt + Shift + H | Move window left |
Alt + Shift + J | Move window down |
Alt + Shift + K | Move window up |
Alt + Shift + L | Move window right |
Alt + Shift + R | Re-apply the tiling layout |
Alt + T | Toggle monocle (full-screen) mode |
Alt + Q | Close the focused window |
Alt + 1-8 | Switch to workspace 1-8 |
Alt + Shift + 1-8 | Send focused window to workspace 1-8 |
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