An AI-maintained fork of Forge, the GNOME Shell extension that provides i3/sway-style tiling window management.
This fork addresses bugs and adds features while the upstream project seeks a new maintainer. Contributions here are intended to be upstreamed when possible. Thanks to @jmmaranan and all original contributors for creating this excellent extension.
- Works on GNOME 45+ (X11 and Wayland)
- Tree-based tiling with vertical and horizontal split containers similar to i3-wm and sway-wm
- Vim-like keybindings for navigation/swapping windows/moving windows in the containers
- Drag and drop tiling
- Support for floating windows, smart gaps and focus hint
- Customizable shortcuts in extension preferences
- Some support for multi-display
- Tiling support per workspace
- Update hint color scheme from preferences
- Stacked and tabbed tiling layouts, plus workspace monocle
- Swap current window with the last active window
- Auto Split or Quarter Tiling
- Show/hide tab decoration via keybinding
- Window resize using keyboard shortcuts
This fork includes significant improvements over the upstream version:
- Keybindings cheatsheet overlay - Quick reference for all shortcuts (
Super+Shift+/) - Portable config sync - Export/import settings and keybindings for backup or sharing
- Arrow key navigation - Arrow keys work alongside vim-style hjkl bindings
- Floating window rules UI - Manage floating window rules directly in preferences
- Screen edge margins - Configurable gaps for compatibility with panels/docks
- Additional keybindings - Config reload, evenly distribute windows, workspace monocle, and more
- More customization - Border radius, tab margins, default layout, adjustable gap limits
- Monitor exclusion - Option to exclude specific monitors from tiling
- Window resize and focus navigation fixes
- App-specific fixes for Chrome, Brave, Steam, Blender, ddterm, and others
- Stacked/tabbed container behavior improvements
- Preview hints and border rendering fixes
- Cross-workspace window operations
- Preferences saving and theme handling
- Comprehensive unit test suite (1,400+ tests, ~88% line coverage) plus a Dockerized E2E suite
- Refactored architecture with focused, extracted managers (see architecture docs)
- Riskier options stay behind clearly-marked experimental toggles
- Does not support dynamic workspaces
- Does not support vertical monitor setup
Build from source:
# Install dependencies (Node.js 20+ and gettext required)
npm install
# Development build: compile and install to ~/.local/share/gnome-shell/extensions/
make dev
# Production build: compile, install, enable extension, restart shell
make prodAfter installation, log out and log back in (or restart GNOME Shell on X11 with Alt+F2, then r).
Full docs live in docs/:
- User guide (
docs/user/) — layouts & tiling, keybindings, theming, window rules, portable config, multi-monitor, troubleshooting. - Developer reference (
docs/dev/) — architecture, rendering pipeline, Mutter compatibility. - Press
Super+Shift+/in-session for the keybinding cheatsheet.
- Window rules:
$HOME/.config/forge/config/windows.json— see window rules and portable config - Stylesheet:
$HOME/.config/forge/stylesheet/forge/stylesheet.css— see theming
GNOME Shell has built in support for workspace management and seems to work well - so Forge will not touch those.
User is encouraged to bind the following:
- Switching/moving windows to different workspaces
- Switching to numbered, previous or next workspace
See CONTRIBUTING.md for environment setup, build/test commands, and code style. Run make help for the full list of targets.
See CONTRIBUTING.md for setup, tests, and code style, and the upstream discussion about the path to merging this fork back into the main project.
Thank you to:
- The original Forge developers - @jmmaranan and all upstream contributors who created this extension
- Michael Stapelberg/contributors for i3
- System76/contributors for pop-shell
- ReworkCSS/contributors for css-parse/css-stringify