> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/mrkai77/loop/llms.txt
> Use this file to discover all available pages before exploring further.
# Keyboard Shortcuts
> Assign custom keyboard shortcuts to perform window actions instantly
## 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
Configure your trigger key in Settings > Keybinds (e.g., Control, Option, or Caps Lock)
Add a new keybind and assign it an action (e.g., Trigger + H for left half)
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
Enter native macOS fullscreen mode
Fill the entire screen (without fullscreen mode)
Maximize with a small margin around edges
Center the window on screen
Use macOS native window centering
Minimize window to dock
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](/features/cycles))
## Configuration
### Adding Keybinds
Navigate to **Settings > Keybinds** and follow these steps:
Create a new keybind entry
Choose from the dropdown menu of available actions
Click the keybind field and press your desired key (the trigger key is automatically included)
Give your keybind a custom name for easy reference
### Trigger Key Options
The base modifier key(s) that activate Loop. Can be a single key or combination.
When enabled, Left Control and Right Control are treated as distinct trigger keys.
Delay before Loop activates (0-1 seconds). Useful to avoid accidental triggers.
Require double-tapping the trigger key to activate Loop.
Use middle mouse button to trigger Loop.
## Implementation Details
Keyboard shortcuts are monitored by the `KeybindTrigger` class using an active event monitor:
```swift Loop/Core/Observers/KeybindTrigger.swift theme={null}
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:
Loop first checks if the pressed keys exactly match a configured keybind
If no match, check for actions that bypass the trigger key requirement
If only the trigger key is pressed, open the radial menu for cursor-based selection
### Event Handling
The keybind system intelligently handles edge cases:
```swift theme={null}
// 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:
```swift theme={null}
init(
_ direction: WindowDirection,
keybind: Set,
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:
```swift theme={null}
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:
```bash Shell Commands theme={null}
# 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 theme={null}
-- 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.