Advanced Usage Guide

This guide covers advanced SamWM features and techniques for power users.

Window Management Mastery

Focus Modes

SamWM supports two focus modes controlled by focus_follows_mouse:

samwm.general({
    focus_follows_mouse = true  -- Click to focus, or hover
    -- focus_follows_mouse = false -- Click-only focus
})

When focus_follows_mouse is enabled, moving your mouse over a window automatically focuses it. When disabled, you must click to focus.

Focus Navigation

Navigate between windows with precision:

Keybinding	Action
`SUPER + J`	Focus next window (cycles)
`SUPER + K`	Focus previous window (cycles)
`SUPER + Tab`	Focus last active window
Click	Focus window under cursor

Window Swapping

Quickly swap window positions:

Keybinding	Action
`SUPER + H`	Swap with left neighbor
`SUPER + L`	Swap with right neighbor
`SUPER + J`	Swap with window below
`SUPER + K`	Swap with window above
`SUPER + Enter`	Swap master with current
`SUPER + Shift + M`	Move window to master position

Resizing Windows

Resize with keyboard shortcuts:

Keybinding	Action
`SUPER + Right`	Grow width by 20px
`SUPER + Left`	Shrink width by 20px
`SUPER + Up`	Grow height by 20px
`SUPER + Down`	Shrink height by 20px

Custom resize amounts:

-- Resize by 50px
samwm.bind("SUPER", "Right", "resize grow_width 50")
samwm.bind("SUPER", "Left", "resize shrink_width 50")

-- Resize by 10px for fine control
samwm.bind("SUPER+SHIFT", "Right", "resize grow_width 10")

Workspace Mastery

Workspace Basics

SamWM supports 10 workspaces, numbered 1-10.

Keybinding	Action
`SUPER + 1-0`	Switch to workspace 1-10
`SUPER + SHIFT + 1-0`	Move window to workspace 1-10

Cycling Workspaces

Use SUPER + Tab to cycle through recent workspaces:

-- Add to config
samwm.bind("SUPER", "Tab", "workspace prev")
samwm.bind("SUPER+SHIFT", "Tab", "workspace next")

Workspace-Specific Layouts

Each workspace can have a different layout:

-- Workspace 1: Master-stack (default)
-- Workspace 2: Dwindle
samwm.bind("SUPER", "2", "workspace 2 && layout dwindle")

Or set via IPC:

samwm-msg workspace 2
samwm-msg setlayout dwindle

Workspace Rules

Auto-assign windows to workspaces:

samwm.windowrule(
    { class = "Firefox" },
    { workspace = "2" }
)

samwm.windowrule(
    { class = "Spotify" },
    { workspace = "3" }
)

Floating Windows

Basic Floating

Toggle floating mode:

samwm.bind("SUPER", "Space", "togglefloating")

Default Floating

Some apps should always be floating:

samwm.windowrule(
    { class = "pavucontrol" },
    { float = true }
)

samwm.windowrule(
    { class = "nm-connection-editor" },
    { float = true }
)

samwm.windowrule(
    { title = "Picture-in-Picture" },
    { float = true }
)

Floating Window Management

Floating windows can be resized and moved with mouse or keyboard:

-- Resize with keyboard
samwm.bind("SUPER", "R", "resize grow_width")  -- After SUPER+Space to enter resize mode

-- Move with keyboard (requires additional config)
-- This is typically done by entering drag mode with SUPER+click

Center Floating Windows

Quickly center a floating window:

-- Move to center (requires custom script or IPC)
os.execute("samwm-msg setprop window_center")

Fullscreen Mode

Toggle fullscreen for focused window:

samwm.bind("SUPER", "F", "fullscreen")

Per-App Fullscreen Rules

Some apps should default to fullscreen:

samwm.windowrule(
    { class = "mpv" },
    { fullscreen = true }
)

samwm.windowrule(
    { class = "YouTube" },  -- Electron apps
    { fullscreen = true }
)

Tab Groups

Create tab groups for related windows:

Keybinding	Action
`SUPER + W`	Create new tab group with focused window
`SUPER + Shift + W`	Add window to current tab group
`SUPER + Tab`	Cycle tabs in group

Tab Group Rules

Auto-group certain apps:

-- Group all terminals in one workspace
samwm.windowrule(
    { class = "Alacritty" },
    { tab_group = true }
)

Multi-Monitor Setup

Basic Multi-Monitor

SamWM automatically detects monitors. Each monitor gets its own workspace set.

Monitor-Specific Rules

-- Send Firefox to secondary monitor
samwm.windowrule(
    { class = "Firefox" },
    { monitor = "DP-2" }
)

Monitor Keybindings

-- Move workspace to specific monitor
samwm.bind("SUPER", "M", "moveworkspace HDMI-A-1")

-- Focus monitor
samwm.bind("SUPER", "XF86Display", "focusmonitor next")

Power User Tips

Efficient Window Management

Use workspace patterns: Keep similar apps on specific workspaces
- Workspace 1: Terminal
- Workspace 2: Browser
- Workspace 3: IDE
- Workspace 4: Communication

Master count optimization: For coding, use 2-3 master windows

samwm.layout({
    master_count = 2  -- Two windows in master
})

Use scratchpad for reference: Keep docs in scratchpad

samwm.bind("SUPER+SHIFT", "B", "scratchpad toggle")

Scripting with IPC

Automate repetitive tasks:

#!/bin/bash
# Focus Firefox or launch it if not running

FOCUSED=$(samwm-msg focused | jq -r '.class')
if [ "$FOCUSED" = "firefox" ]; then
    samwm-msg workspace 2
else
    samwm-msg workspace 2 && firefox &
fi

Workspace Layout Presets

Create preset layouts:

-- coding.lua
samwm.layout({ master_factor = 0.4 })
samwm.layout({ master_count = 2 })

-- writing.lua
samwm.layout({ master_factor = 0.6 })
samwm.layout({ master_count = 1 })

-- Load preset
samwm.switch_layout("coding")

Dynamic Configuration

Update config based on time:

-- Auto-switch layout based on time
local hour = os.date("%H")
if tonumber(hour) >= 18 then
    samwm.layout({ master_factor = 0.7 })
else
    samwm.layout({ master_factor = 0.55 })
end

Performance Optimization

SamWM is designed for high performance. Key optimizations:

Animation Control

Animations are disabled by default. To enable:

samwm.appearance({
    animations = {
        window_move = 150,  -- milliseconds
        window_focus = 100,
        workspace_switch = 200,
        easing = "easeOut"  -- easeIn, easeOut, easeInOut, linear
    }
})

Reduce Redraws

Disable animations for maximum performance:

samwm.animation({
    enabled = false
})

GPU Acceleration

Ensure your GPU is properly configured:

samwm.general({
    -- Enable direct scan-out if supported
    direct_scan_out = true
})

Emergency Commands

When something goes wrong:

Command	Action
`SUPER + M`	Exit SamWM
`SUPER + Shift + R`	Reload configuration
`pkill samwm`	Force kill from terminal
`samwm-msg reload`	Reload via IPC

Custom Actions

Create custom keybinding actions:

-- Example: Cycle through all layouts
samwm.bind("SUPER", "R", "switchlayout")

-- Example: Toggle all windows floating
samwm.bind("SUPER+SHIFT", "Space", "exec samwm-msg exec toggle-all-floating")

Advanced Window Rules

Regex Matching

Match windows using patterns:

-- Match any browser
samwm.windowrule(
    { class = "firefox|chromium|chrome" },
    { workspace = "2" }
)

-- Match browser development tools
samwm.windowrule(
    { title = ".*DevTools.*" },
    { float = true }
)

Multiple Match Criteria

Combine multiple conditions:

-- Float only floating terminals
samwm.windowrule(
    { class = "Alacritty", title = "float" },
    { float = true }
)

Action Stacking

Apply multiple actions:

samwm.windowrule(
    { class = "Spotify" },
    {
        float = true,
        workspace = "3",
        center = true
    }
)

Expert Techniques

Window History

Track recently focused windows:

-- Enable in config
samwm.general({
    track_focus_history = true
})

-- Access via IPC
samwm-msg get focus_history

Layout Locking

Prevent accidental layout changes:

samwm.bind("SUPER+CTRL", "L", "locklayout")
samwm.bind("SUPER+CTRL", "U", "unlocklayout")

Gap Optimization

Fine-tune gap calculations:

samwm.general({
    gaps_inner = 4,
    gaps_outer = 8,
    smart_gaps = true  -- Disable when single window
})

-- Per-workspace gaps
samwm.workspace(1, function()
    samwm.general({ gaps_inner = 10 })
end)

Tabs & Containers