📣 Follow the development journey on Mastodon! Progress updates, design decisions, and behind-the-scenes posts: floss.social/@CleoMenezesJr
Rethinking window management for GNOME Shell
A GNOME Shell extension that provides automatic window tiling in a mosaic layout. Inspired by GNOME's vision for rethinking window management, Mosaic WM intelligently arranges windows to maximize screen space while maintaining visual harmony.
Warning
Experimental Extension: This extension is under active development and may contain bugs or unexpected behavior. Use at your own risk. Please report any issues.
Important
Requires GNOME Shell 50+ (Mutter 50). See this post for details.
Traditional window management forces users to manually position and resize windows. Mosaic WM takes a different approach:
- Automatic: Windows organize themselves intelligently
- Adaptive: Layout responds to your workflow
- Minimal: No manual tiling or complex keyboard shortcuts needed
- Visual: See your workspace at a glance
This aligns with GNOME's philosophy of reducing cognitive load and letting users focus on their work, not window management.
- 🎯 Automatic Mosaic Layout: Windows are automatically arranged in an optimal layout using a radial packing algorithm
- 🔄 Smart Resize: Before moving windows to new workspaces, the extension tries to resize existing windows to make space
- 📐 Edge Tiling (Snap Zones): Drag windows to screen edges for half/quarter tiling - remaining windows adapt to the available space
- 🔀 Window Swapping: Drag a window onto another to swap their positions
- 🚀 Intelligent Overflow: Windows that don't fit are moved to existing workspaces when possible, or create new ones
- 🖥️ Fullscreen Support: Fullscreen and maximized windows automatically get dedicated workspaces
- 🔙 Reverse Smart Resize: When windows leave, remaining windows expand back to their original sizes
- ✨ Directional Momentum: Windows slide in from the direction they came from, with a bouncy animation
- 🎬 Smooth Transitions: All layout changes are animated for a polished feel
- 👁️ Visual Feedback: Live preview during drag operations shows where windows will land
- ⌨️ Keyboard Shortcuts: Swap windows with keyboard (configurable)
- 🖥️ Multi-Monitor: Works across multiple displays (experimental)
- 🎛️ Per-Workspace Toggle: Enable or disable mosaic on individual workspaces from the Quick Settings menu
- 🔘 Global Toggle: Master switch to quickly enable/disable mosaic on all workspaces
- 📍 Dynamic Indicator: Top bar icon shows mosaic status for the current workspace
# Clone the repository
git clone https://github.com/CleoMenezesJr/MosaicWM.git
cd MosaicWM
# Install the extension
./scripts/build.sh -i
# Log out and log back in, then enable
gnome-extensions enable [email protected]- Download the latest release from GitHub
- Extract to
~/.local/share/gnome-shell/extensions/[email protected]/ - Disable debug logging: Edit
extension/logger.jsand setconst DEBUG = false; - Restart GNOME Shell (log out and log back in)
- Enable via Extensions app or:
gnome-extensions enable [email protected]
Once enabled, the extension works automatically:
- Open windows: They'll be automatically tiled
- Drag windows: Click and drag to reorder
- Maximize/Fullscreen: Window moves to its own workspace
- Minimize: Window is excluded from tiling
- Too many windows: Overflow windows move to new workspace
- GNOME Shell 50+
- Git
# Install the extension
./scripts/build.sh -i
# Test in a nested GNOME Shell session
./scripts/run-gnome-shell.shDebug logging is enabled by default for development. To enable verbose debug logs, edit extension/logger.js and set:
const DEBUG = true;Tip
For production/installation, set DEBUG = false to reduce CPU usage.
For debugging and development tips, see the GJS Extension Development Guide.
View logs in real-time:
# Monitor extension logs
journalctl -f -o cat /usr/bin/gnome-shell | grep -i mosaic
# Or use GNOME's Looking Glass (Alt+F2 → 'lg')
# Navigate to Extensions tab to see errors- Functions: camelCase (
tileWorkspaceWindows) - Classes: PascalCase (
WindowDescriptor) - Constants: UPPER_CASE (
WINDOW_SPACING) - Private properties: Prefix with
_(this._wmEventIds) - Comments: Use
//for inline comments, avoid JSDoc blocks
This extension is designed for Wayland sessions and leverages modern compositor integration for proper window positioning and multi-monitor support.
For more information on GNOME Shell extension development:
Note
This project is in early development with rapidly changing code. Code contributions are not currently accepted due to the high velocity of changes.
Best ways to contribute right now:
- 🧪 Testing: Try the extension and explore edge cases
- 🐛 Bug Reports: Open issues with detailed reproduction steps
- 💡 Feature Ideas: Share suggestions in GitHub Issues
- ✍️ Documentation: Always add comments explaining what the code is doing (it helps the maintainer follow the logic!)
- 🏛️ Compliance: All contributions must follow the GNOME Shell Extensions Review Guidelines.
Important
For development: Ensure DEBUG = true in extension/logger.js to see verbose logs.
This project is licensed under the GNU General Public License v2.0 or later - see the LICENSE file for details.
- Kudos to heikkiket/window-mosaic-mode for the original concept and implementation
- Inspired by Tobias Bernard's vision for GNOME window management
- GNOME Shell team for the excellent extension API
- Contributors and testers
Caution
The interaction between mosaic layout and edge tiling (snap zones) is experimental.
Current limitations:
- Multi-monitor requires "Workspaces on all displays" setting (Settings → Multitasking). "Workspaces on primary display only" is not yet supported. (#30)
- Overview drag-drop may have issues in some scenarios
- Edge tiling overflow preview not yet animated
Made with ❤️ for the GNOME community