Skip to main content

​
Overview

Loop’s keyboard shortcut system allows you to assign any key combination (using the trigger key) to initiate window manipulation actions. This provides a fast, precise alternative to the radial menu for users who prefer keyboard-driven workflows.

​
How Keyboard Shortcuts Work

Loop uses a trigger key system. The trigger key acts as a modifier that must be held (or pressed) in combination with other keys to activate window actions.

​
Basic Workflow

1

Set your trigger key

Configure your trigger key in Settings > Keybinds (e.g., Control, Option, or Caps Lock)
2

Create a keybind

Add a new keybind and assign it an action (e.g., Trigger + H for left half)
3

Use the shortcut

Hold the trigger key and press your assigned key to execute the action
To use Caps Lock as your trigger key, you’ll need to remap it to Control in System Settings > Keyboard > Modifier Keys, then select Right Control in Loop.

​
Available Actions

Loop provides an extensive collection of window actions organized by category:

​
General

Fullscreen

Enter native macOS fullscreen mode

Maximize

Fill the entire screen (without fullscreen mode)

Almost Maximize

Maximize with a small margin around edges

Centre

Center the window on screen

MacOS Centre

Use macOS native window centering

Minimize

Minimize window to dock

Hide

Hide the application

​
Halves

Position windows to fill half of the screen:
  • Top Half: Upper half of screen
  • Bottom Half: Lower half of screen
  • Left Half: Left half of screen
  • Right Half: Right half of screen

​
Quarters

Position windows in screen corners:
  • Top Left Quarter
  • Top Right Quarter
  • Bottom Left Quarter
  • Bottom Right Quarter

​
Thirds

Horizontal Thirds:
  • Left Third, Left Two Thirds
  • Horizontal Center Third
  • Right Third, Right Two Thirds
Vertical Thirds:
  • Top Third, Top Two Thirds
  • Vertical Center Third
  • Bottom Third, Bottom Two Thirds

​
Screen Switching

Move windows between displays:
  • Next Screen / Previous Screen: Cycle through displays
  • Left/Right/Top/Bottom Screen: Move to specific adjacent screen

​
Window Manipulation

Size Adjustment:
  • Larger, Smaller: Resize proportionally
  • Scale Up, Scale Down: Alternative sizing methods
Directional Shrink:
  • Shrink Top, Bottom, Right, Left
  • Shrink Horizontal, Shrink Vertical
Directional Grow:
  • Grow Top, Bottom, Right, Left
  • Grow Horizontal, Grow Vertical
Movement:
  • Move Up, Down, Right, Left

​
Special Actions

  • Initial Frame: Restore window to its original position
  • Undo: Revert to previous window state
  • Custom: Create custom window sizes and positions
  • Cycle: Define action sequences (see Cycles)

​
Configuration

​
Adding Keybinds

Navigate to Settings > Keybinds and follow these steps:
1

Click 'Add'

Create a new keybind entry
2

Select an action

Choose from the dropdown menu of available actions
3

Record your shortcut

Click the keybind field and press your desired key (the trigger key is automatically included)
4

Name it (optional)

Give your keybind a custom name for easy reference

​
Trigger Key Options

​
Trigger Key
key combination
required
The base modifier key(s) that activate Loop. Can be a single key or combination.
​
Treat left and right keys differently
toggle
default:"false"
When enabled, Left Control and Right Control are treated as distinct trigger keys.
​
Trigger delay
number
default:"0"
Delay before Loop activates (0-1 seconds). Useful to avoid accidental triggers.
​
Double-click to trigger
toggle
default:"false"
Require double-tapping the trigger key to activate Loop.
​
Middle-click to trigger
toggle
default:"false"
Use middle mouse button to trigger Loop.

​
Implementation Details

Keyboard shortcuts are monitored by the KeybindTrigger class using an active event monitor:
Loop/Core/Observers/KeybindTrigger.swift
final class KeybindTrigger {
    private var eventMonitor: ActiveEventMonitor?
    
    func start() async {
        let eventMonitor = ActiveEventMonitor(
            events: [.keyDown, .keyUp, .flagsChanged]
        ) { [weak self] event -> ActiveEventMonitor.EventHandling in
            // Process keybind events
            let result = self?.performKeybind(
                type: event.type,
                isARepeat: event.getIntegerValueField(.keyboardEventAutorepeat) == 1,
                flags: filteredFlags,
                isLoopOpen: isLoopOpen
            )
            
            return result == .consume ? .ignore : .forward
        }
        eventMonitor.start()
    }
}

​
Keybind Resolution

Loop uses a multi-tier keybind resolution system:
1

Check for exact match

Loop first checks if the pressed keys exactly match a configured keybind
2

Check bypassed actions

If no match, check for actions that bypass the trigger key requirement
3

Open radial menu

If only the trigger key is pressed, open the radial menu for cursor-based selection

​
Event Handling

The keybind system intelligently handles edge cases: 
// Prevent conflicts with system shortcuts
refreshSystemKeybindCacheIfNeeded()
if result != .opening, 
   event.type == .keyDown, 
   systemKeybindCache.contains(pressedKeys) {
    closeLoop(forceClose: true)
}
Loop automatically closes when system shortcuts (like screenshot commands) are detected to prevent conflicts.

​
Bypassing the Trigger Key

Some actions can be configured to bypass the trigger key requirement: 
init(
    _ direction: WindowDirection,
    keybind: Set<CGKeyCode>,
    bypassTriggerKey: Bool? = nil
) {
    self.bypassTriggerKey = bypassTriggerKey
    // ...
}
This allows you to create direct keyboard shortcuts without needing to hold the trigger key.

​
Repeatable Actions

Certain actions automatically repeat when you hold down the keys: 
var canRepeat: Bool {
    willManipulateExistingWindowFrame || 
    direction.willFocusWindow || 
    direction == .undo
}
Repeatable actions include:
  • Window resizing (grow, shrink, larger, smaller)
  • Window movement (move up, down, left, right)
  • Focus switching
  • Undo

​
URL Scheme Integration

You can trigger Loop actions programmatically using URL schemes:
Shell Commands
# Trigger specific directions
open "loop://direction/right"     # Move to right half
open "loop://direction/left"      # Move to left half

# Execute window actions
open "loop://action/maximize"     # Maximize window
open "loop://screen/next"         # Move to next screen

# List available commands
open "loop://list/all"            # All commands
open "loop://list/actions"        # Window actions only
open "loop://list/keybinds"       # Custom keybinds
AppleScript
-- AppleScript examples
tell application "Loop" to activate
open location "loop://direction/left"
You can create shell scripts that chain multiple Loop actions together for complex window arrangements.

​
Best Practices

Use mnemonic associations: H for left Half, L for right (like vim), M for Maximize, etc.
Don’t override important system shortcuts or application-specific commands.
Begin with a few essential shortcuts (halves, maximize, center) and expand gradually.
Instead of memorizing many shortcuts, use cycles to group related actions under one keybind.

Build docs developers (and LLMs) love

Get started for freeTalk to us