📣 Follow the development journey on Mastodon! Progress updates, design decisions, and behind-the-scenes posts: floss.social/@CleoMenezesJr
📣 Join the testers room on Matrix! #mosaicwm:matrix.org
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
- Miniature Overflow: When too many windows share a workspace, the oldest ones shrink into small interactive thumbnails. They stay visible and clickable without cluttering the layout
- One-click Restore: Click any miniature to bring it back to full size. The previously focused window becomes the new miniature seamlessly
- Overview Integration: Miniatures maintain their scale and position when entering or leaving the GNOME Overview
- Intelligent Overflow: Windows that can't be miniaturized (e.g. they hit minimum size) 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 close or are miniaturized, remaining windows expand back toward their preferred 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 mosaicwm@cleomenezesjr.github.io- Download the latest release from GitHub
- Extract to
~/.local/share/gnome-shell/extensions/mosaicwm@cleomenezesjr.github.io/ - 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 mosaicwm@cleomenezesjr.github.io
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: Extra windows shrink into small thumbnails. Click one to bring it back to focus
- 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:
If Mosaic WM has been useful to you, consider supporting its 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: Add comments explaining the WHY: constraints, invariants, and non-obvious behavior. Well-named code already explains the what.
- 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
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