wakem - Window Adjust, Keyboard Enhance, and Mouse

A cross-platform window/keyboard/mouse enhancer.

Quick Start

Current release: 0.1.8

1. Installation

Using Install Script

Windows:

# Download the install script
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/wang-q/wakem/master/scripts/install.ps1" -OutFile "install.ps1"

# Run the install script (auto-detects local build or downloads from GitHub)
.\install.ps1

The installer will:

• Download the latest release from GitHub (or use local build if available)
• Install to %LOCALAPPDATA%\Programs\wakem\
• Create configuration directory at %APPDATA%\wakem\
• Set up auto-start on login

Build from Source

Windows:

# Clone the repository
git clone https://github.com/wang-q/wakem.git
cd wakem

# Build
cargo build --release

# Install using the script (will use local build)
.\scripts\install.ps1

macOS:

# Clone the repository
git clone https://github.com/wang-q/wakem.git
cd wakem

# Build
cargo build --release

# Run directly
./target/release/wakem

2. Configuration

Windows:

The install script automatically:

• Creates the configuration directory at %APPDATA%\wakem\
• Installs example configs: minimal.toml, navigation_layer.toml, window_manager.toml
• Sets window_manager.toml as the default config.toml

macOS:

Configuration directory: ~/Library/Application Support/wakem/

# Create config directory
mkdir -p ~/Library/Application\ Support/wakem

# Copy example config
cp examples/window_manager.toml ~/Library/Application\ Support/wakem/config.toml

3. Start

wakem           # Start daemon + tray (GUI mode, no console on Windows)
wakem daemon    # Start daemon only
wakem tray      # Start tray only (daemon must be running)

4. Client Commands

# Global options
--instance, -i    Specify instance ID (default: 0, for multi-instance management)

# Basic commands
wakem status          # View service status
wakem reload          # Reload configuration
wakem save            # Save current configuration to file
wakem enable          # Enable mapping
wakem disable         # Disable mapping
wakem config          # Open configuration folder
wakem instances       # List running instances

# Macro commands
wakem record my-macro        # Start recording macro (press Ctrl+Shift+Esc to stop)
wakem stop-record            # Stop recording macro
wakem play my-macro          # Play macro
wakem macros                 # List all macros
wakem bind-macro my-macro F1 # Bind macro to hotkey
wakem delete-macro my-macro  # Delete macro

Features

1. Window Management (Window Adjust)

Configuration

See examples/window_manager.toml for key bindings configuration (defines Hyper key, shortcuts, etc.).

Symbol	Key
hyper	ctrl+alt+cmd
	ctrl+win+alt
	capslock
hyperShift	hyper+shift

Movement

• Center window. Hyper+C/Backspace/Delete/ForwardDelete

• Move to edges

  • Left edge - Hyper+Home
  • Right edge - Hyper+End
  • Top edge - Hyper+PageUp
  • Bottom edge - Hyper+PageDown

• Move across monitors. Hyper+J/K

Resize

• Fixed aspect ratio windows

  • Native aspect ratio (cycle zoom: 1.0, 0.9, 0.7, 0.5). HyperShift+M/Enter
  • 4:3 aspect ratio (cycle zoom: 1.0, 0.9, 0.7, 0.5). Hyper+M/Enter

• Width adjustment

  • Cycle ratios: 3/4 → 3/5 → 1/2 → 2/5 → 1/4. Hyper+Left/Right
  • Vertical half-screen. HyperShift+Left/Right

• Height adjustment

  • Cycle ratios: 3/4 → 1/2 → 1/4. Hyper+Up/Down
  • Horizontal half-screen. HyperShift+Up/Down

Other

• Switch between same-app windows. Alt+`
• Window always-on-top/transparency - configure custom hotkeys

2. Keyboard Enhancement (Keyboard Enhance)

• Key remapping - CapsLock to Backspace/Esc, swap Ctrl/Alt, CapsLock as Hyper key, etc.
• Shortcut layer system - Hold (press and hold to activate) / Toggle (toggle activation) modes
• Arrow key layer - CapsLock + H/J/K/L as arrow keys (Vim style)
• Application shortcuts - Define exclusive shortcuts for specific applications (context-aware)
• Quick launch - Hotkeys to launch commonly used programs (supports commands with parameters)

3. Mouse Enhancement (Mouse Enhance)

• Wheel acceleration - Automatically increase scroll distance based on scroll speed
• Horizontal scroll - Vertical wheel becomes horizontal when holding modifier key
• Volume control - Wheel adjusts system volume when holding modifier key
• Brightness control - Wheel adjusts screen brightness when holding modifier key
• Wheel inversion - Optionally invert wheel direction

4. Macro Recording & Playback (Macro)

• Record macros - Record keyboard/mouse action sequences, intelligently filtering standalone modifier keys
• Play macros - Trigger recorded macros via hotkeys or command line
• Macro management - View, bind, delete macros, with persistent configuration file storage
• Modifier key state tracking - Automatically records and reconstructs modifier key states during recording

5. Multi-Instance Support

• Run multiple wakem instances simultaneously, each with independent configuration and ports
• Specify instance via --instance N parameter
• Automatic port allocation: instance0 = 57427, instance1 = 57428, ...

6. Debug Features

• Display window info. Hyper+W
• Display test notification. HyperShift+W

Build

# Development build
cargo build

# Release build
cargo build --release

# Run tests (171+ tests)
cargo test

# Run benchmarks
cargo bench

# Code quality checks
cargo fmt
cargo clippy -- -D warnings

Documentation

• Configuration Guide - Complete keyboard, window management, mouse configuration instructions
• Developer Documentation - Architecture explanation, development plans, and API reference
• Macro System Documentation - Detailed macro recording and playback usage instructions
• Key Names Reference - Complete list of supported key names and scan codes

Platform Support

Platform	Status	Notes
Windows	Full support	All features implemented
macOS	In development	Core features working, some advanced features pending
Linux	Planned	Wayland support planned for future

Reference Projects

• keymapper - Cross-platform key remapping tool
• AutoHotkey - Windows automation scripting tool
• window-switcher - Rust window switching tool
• mrw - Personal project, concise window management
• Size looping behavior from spectacle.
• Hammerspoon implementation reference from this post.
• AutoHotkey implementation reference from here.

License

MIT License