GPilot

A GNOME Shell extension that enhances window management with visual outlines, customizable keybindings, and intelligent window positioning.

Context

The README is mainly summarized by AI, so using this section for a quick human note and motivations.

• GNOME Mutter's forces client side window decorations on Wayland. This let's window border to be invisible in many windows, eg. Electron based apps like Obisian, VS Code, Slack, Discord, etc and makes it really annoying to work with.
• This extension taps into compositor and makes it to draw a simple border overlay efficiently. The border can be shadow blur or a simple outline.
• Turns out this is more annoying in GNOME since mutter prefers CSR, each app makes it's own assumptions of margins and where it draws, so the extension by default operates in whitelist only mode, being able with specific known border insets that can be customized.
• In addition, this also helps overriding global shortcuts to provide more sensible functionality, like moving window across screens. GNOME's default messes up the window sizes and places them in weird off screen locations when they don't fit in the monitor dimensions.
  • Super + X: window_optsize by default, auto sizes windows to a 0.8x of the monitor size if it detects that it the window is too large when moved across monitors and it auto positions them when GNOME would otherwise place it out of bounds.
  • These shortcuts also moves the window cursor's alongside, so it's provide a much more intuitive behavior.
• The extension is designed generically as stateless commands, with a key bind manager and provides more convenience commands to offset GNOME's quirky behaviors that needs to tap into mutter.

Features

🎯 Window Outlines

• Visual Focus Indicators: Configurable borders and shadows for focused windows
• Per-Application Rules: Customize outline styles based on window class, title, or process name
• Smart Insets: Precise border positioning accounting for window decorations
• Dual Styling: Support for both border and shadow outline modes

⌨️ Enhanced Window Management

• Optimal Window Sizing: Intelligent window resizing (Super+X)
• Vertical Maximization: Maximize windows vertically only (Super+Z)
• Multi-Monitor Support: Move windows between monitors (Super+Shift+Arrow Keys)
• Window Tiling: Left/right tiling with Super+Ctrl+Arrow Keys

🎛️ Configuration

• KDL Configuration Format: Human-readable configuration files
• Panel Menu Integration: Optional panel menu for quick access
• Debug Mode: Comprehensive logging for troubleshooting

Installation

Quick Install

git clone https://github.com/prasannavl/gpilot.git
cd gpilot
./scripts/install-ext.sh

Manual Installation

1. Clone the repository:

   git clone https://github.com/prasannavl/gpilot.git
   cd gpilot

2. Install dependencies and build:

   npm install
   npm run build

3. Install the extension:

   ./scripts/install-ext.sh

Or alternatively, just to pack and install on your own: ./scripts/pack-ext.sh

4. Log out and log back in.

5. Enable the extension:

   gnome-extensions enable gpilot@prasannavl.com

Configuration

GPilot uses KDL (KDL Document Language) for configuration. The config file is located at ~/.config/gpilot/config.kdl. Can be edited through preferences window.

Default Configuration Structure

globals {
    width 4                    // Border width for focused windows
    inactiveWidth 4           // Border width for inactive windows
    color r=0.2 g=0.6 b=0.9 a=0.4        // Focused window color (RGBA)
    inactiveColor r=0.4 g=0.4 b=0.4 a=0.2 // Inactive window color (RGBA)
    spread 1                  // Shadow spread
    blurRadius 12             // Shadow blur radius
    panelMenu "false"         // Show panel menu
    debug "false"             // Enable debug logging
}

fn_key_binds {
    window_optsize "<Super>x"
    window_maximize_vertically "<Super>z"
    window_to_monitor_left "<Super><Shift>Left"
    window_to_monitor_right "<Super><Shift>Right"
    window_to_monitor_up "<Super><Shift>Up"
    window_to_monitor_down "<Super><Shift>Down"
    window_tile_left "<Super><Ctrl>Left"
    window_tile_right "<Super><Ctrl>Right"
}

windows {
    all style="off"           // Default: no outlines
    
    // Application-specific rules
    "org.gnome.terminal" match="class" style="border" top=22 right=25 bottom=27 left=24
    "google-chrome" match="class" style="border" top=10 right=16 bottom=32 left=16
    firefox match="class" style="border" top=22 right=25 bottom=27 left=25
    code match="class" style="border"
    
    // Pattern matching examples
    chrome- match="class" style="border" top=10 right=16 bottom=32 left=16  // Matches chrome-*
}

Window Rules

Window rules support multiple matching criteria:

• match="class": Match by window class (default)
• match="title": Match by window title
• match="process": Match by process name
• match="app": Match by application name

Style options:

• style="border": Draw colored border
• style="shadow": Draw drop shadow
• style="off": No outline

Inset values (top, right, bottom, left) adjust border positioning to account for window decorations.

Default Keybindings

Keybinding	Action
Super + X	Resize window to optimal size
Super + Z	Maximize window vertically
Super + Shift + ←/→/↑/↓	Move window to adjacent monitor
Super + Ctrl + ←/→	Tile window left/right

All keybindings are customizable through the configuration file.

Development

Requirements

• Node.js and npm
• TypeScript
• GNOME Shell development libraries

Building

# Install dependencies
npm install

# Type checking
npm run typecheck

# Build extension
npm run build

# Watch mode for development
npm run typecheck:watch

Project Structure

src/
├── extension.ts              # Main extension entry point
├── prefs.ts                 # Preferences UI
├── common/
│   ├── config.ts            # Configuration management
│   └── utils.ts             # Utility functions
└── modules/
    ├── commands.ts          # Window management commands
    ├── keybindmanager.ts    # Keybinding handling
    ├── panelmenu.ts         # Panel menu integration
    └── windowoutlinemanager.ts # Window outline rendering

Compatibility

• GNOME Shell: 48.x
• Operating System: Linux distributions with GNOME
• Architecture: x86_64, ARM64

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and test thoroughly
4. Commit with descriptive messages
5. Push and create a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

• Built with GJS TypeScript bindings
• Configuration powered by KDL
• Inspired by various GNOME Shell window management extensions

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

GPilot - Prasanna's GNOME Co-pilot for enhanced window management