Forge is a GNOME Shell extension that brings i3/sway-style tiling window management to GNOME. This repository (lukebmay/forge) is a product fork focused on multi-monitor reliability, tabbed layouts, a forge control CLI, and a daily-driver workflow.

Works on GNOME 45+ (X11 and Wayland). Extension UUID: forge@jmmaranan.com (same as upstream — installs replace each other in place).

Thanks to @jmmaranan, @jcrussell, and all original contributors.

Upstream EGO is lightly maintained and has sought a new maintainer. The community fork is the better code base for modern GNOME; this tree builds on that base for reliability and scripting.

Pull community updates with the upstream remote (upstream/main); day-to-day development and installs stay on this repo.

• Tree-based tiling with horizontal and vertical splits (i3/sway-like)
• Vim-style navigation, swap, and move keybindings
• Drag-and-drop tiling with preview hints
• Floating windows, smart gaps, and focus borders
• Stacked and tabbed container layouts; workspace monocle
• Per-workspace tiling; multi-monitor support
• Window resize via keyboard; auto-split / quarter tiling
• Customizable shortcuts in extension preferences

Improvements that land in this tree via the jcrussell lineage:

Features

• Keybindings cheatsheet overlay
• Portable config sync (export/import settings and keybindings)
• Arrow-key navigation alongside hjkl
• Floating window rules UI in preferences
• Screen edge margins (panels/docks)
• Extra bindings: config reload, evenly distribute, workspace monocle, …
• More appearance options (border radius, tab margins, gap limits, default layout)
• Monitor exclusion from tiling

Bug fixes

• Resize and focus navigation reliability
• App-specific fixes (Chrome, Brave, Steam, Blender, ddterm, …)
• Stacked/tabbed container behavior
• Preview hints and border rendering
• Cross-workspace window operations
• Preferences save and theme handling

Engineering

• Large unit-test suite (1,600+ tests) and Dockerized E2E
• Refactored managers and clearer architecture (docs/dev/architecture.md)
• Riskier options behind experimental toggles

Product work aimed at surviving real multi-monitor sessions and scripting the desk:

• GNOME Shell 45+
• To build from source: Node.js 20+, npm, make, gettext (msgfmt), glib-compile-schemas

git clone https://github.com/lukebmay/forge.git
cd forge
./install

That builds the extension, installs it under ~/.local/share/gnome-shell/extensions/forge@jmmaranan.com, enables it, puts the forge CLI on ~/.local/bin/forge, and reloads GNOME Shell on X11.

# after install (ensure ~/.local/bin is on PATH)
forge ping
forge tree
forge help

Already on extensions.gnome.org Forge? ./install migrates with an automatic settings backup (dconf + ~/.config/forge). Prefs and keybindings are kept when the schemas allow.

Daily reinstall after pulling code:

git pull
forge install          # or: ./install
# or: forge update     # clean master: fetch → pull if new → always install

Remove (keeps prefs):

forge uninstall
# wipe config too:
forge uninstall --purge-config

After any install that does not reload Shell: on X11 use Alt+F2 → r, or killall -HUP gnome-shell; on Wayland, log out and back in.

• Cheatsheet: Safe kit default Ctrl+Super+/ (Vim kit: Super+Shift+/)
• Reload config / theme: Super+Shift+r (or your kit’s reload chord)
• Group chrome (tab ↔ stack): Safe Ctrl+Super+g · Vim Shift+Super+n
• Merge into tabbed group: Safe Ctrl+Super+m · Vim Shift+Super+m
• Layout debug overlay: Ctrl+Super+d
• Preferences: Extensions app → Forge, or gnome-extensions prefs forge@jmmaranan.com
• Keybind kits CLI: forge keybind apply vim (also safe / i3; backup/list)

User guide:

Talks to the enabled extension over DBus. Install also places it at ~/.local/bin/forge.

forge help
forge tree                              # tiling forest (JSON)
forge tree --monitor=0 --compact
forge focus 'class:firefox'
forge launch nautilus                   # resolve .desktop + place after LFT
forge launch ghostty --monitor=1
forge launch nautilus --path=mo1ws0/1/1

# Named layout profiles
forge layout help
forge layout list
forge layout save mydesk
forge layout mydesk --dry-run
forge layout mydesk

# Install helpers (no DBus)
forge install
forge update
forge uninstall

Full install/migrate script reference: scripts/forge/README.md.

GNOME still owns workspaces. Bind workspace switch/move in GNOME Settings as you prefer; Forge does not replace that.

• No dynamic workspaces
• Limited vertical-monitor support
• Multi-monitor blank/wake is much more robust than stock, but edge thrash cases can still need a config reload (Super+Shift+r) or a retab
• Stack mode is off by default (tab-first; enable in prefs if you want it)

See CONTRIBUTING.md. Branch off master. Prefer small, tested patches (npm test / make unit-test).

Issues for this fork: https://github.com/lukebmay/forge/issues
Community base: https://github.com/jcrussell/forge/issues
Original project discussion on maintainership: forge-ext discussion #501.

• Original Forge — @jmmaranan and upstream contributors
• Community fork — @jcrussell and contributors
• Michael Stapelberg / i3; System76 / pop-shell; ReworkCSS css-parse/stringify