Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Single test / focused run:
hotkeys, reload flow, and Command Overlay) or run targeted helper tools in `tools/`.
- Focused validation (pick relevant items):
- Launch `harken.ahk` with a clean config and verify: super hotkeys, window cycling, overlay.
- If virtual desktops touched: test `super+alt+h/l`, mapped desktop hotkeys, and tray indicator.
- If virtual desktops touched: test `super+j/k`, `super+shift+j/k`, mapped desktop hotkeys, and tray indicator.

## Code Style Guidelines

Expand Down
19 changes: 18 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,21 +12,38 @@ All notable changes to this project are documented here. This changelog is human
- Virtual desktop scroll navigation and move-window scroll support (`super+scroll` & `super+alt+shift+scroll`).
- Optional desktop switch curtain to mask brief background flashes.
- Project now uses CHANGELOG.md
- Optional `modes.carousel` mode with niri-like horizontal focus/move behavior scoped to current virtual desktop and active monitor.
- Carousel mode desktop move follow toggle (`super+f`) and native overview shortcut (`super+o`).
- Carousel mode width controls (`super+-` / `super+=`) and auto-maintained trailing empty desktop support.
- Persistent carousel status bar with desktop count, active desktop highlight, and current strip window titles.
- `[[virtual_desktop.N]]` desktop mappings now support `super+<key>` goto and `super+alt+<key>` no-follow window expel.

### Changed
- Double-super now opens native Task View; move mode is entered from command mode, and h/j/k/l navigate Task View.
- Default non-carousel hotkeys now follow a niri-like layout: `super+h/l` focus, `super+j/k` desktop navigation, `super+ctrl+h/j/k/l` window movement, and `super+shift+j/k` window-to-desktop moves.
- Centered resize moved to `super+alt+arrows`; monitor focus/move now uses `super+u/i` and `super+shift+u/i`.
- Legacy `super+alt+h/l` and `super+alt+shift+h/l` virtual desktop defaults are disabled, while config support remains.
- Double-super overview is now disabled by default and can be restored with `window.super_double_tap_action = "overview"`.
- Move mode is entered from command mode, and h/j/k/l navigate Task View.
- Super+scroll switches virtual desktops (replacing the prior super+alt+scroll combo).
- Config flow favors `config_watch` instead of a dedicated reload section.
- Example config updates (apps list and focus border thickness).
- App matching now uses cached window metadata and PID-based lookups for off-desktop windows, with focus diagnostics logging.
- README adds a comparison section with similar tools.
- Config validation favors warnings over hard errors where possible.
- Window manager grid movement hotkeys yield to carousel mode when active.
- Carousel mode now auto-relayouts after external focus changes (Task View selection and app focus hotkeys).
- Carousel tile width adjustments now persist per app executable across restarts.
- Carousel strip order now restores best-effort per desktop+monitor scope using app executable order.
- Non-carousel desktop switching can now skip the post-switch wait for faster focus changes, and trailing empty desktop management now creates and prunes desktops to keep exactly one empty desktop at the end.
- Status bar enablement is now controlled globally from `virtual_desktop.status_bar`, with optional visibility in non-carousel mode.

### Fixed
- Mapped desktop hotkeys now use true super-combo registration so `super+1/2/3/4/5` works with CapsLock/F24 super keys.
- Window walker rendering issues when the resolution changes.
- Window cycling now includes more than two tiles reliably.
- Grid snapping edge cases.
- EnumWindows callback signature.
- UI Automation no longer sets the Windows screen-reader flag, avoiding PowerShell PSReadLine warnings.

## [0.2.1] - 2026-02-07
### Added
Expand Down
78 changes: 56 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ Harken allows a keyboard-centered workflow on Windows: a single super modifier,



Launch-or-focus a program with `super + [letter]`, or directionally change window focus with `alt + h/l/j/k` (left, right, down, up) and `alt + [` / `alt + ]` for back/forward in a stack.
Launch-or-focus a program with `super + [letter]`, or directionally change window focus with `super + h/l` (left/right) and `super + [` / `super + ]` for back/forward in a stack.
![Alt text](docs/assets/focus.gif)

Cycle centered window widths with `super + spacebar`.
Expand All @@ -49,15 +49,17 @@ Cycle centered window widths with `super + spacebar`.
Maximizes/restores with `super + m`.
![Alt text](docs/assets/maximize.gif)

Move a window with `super + h/j/k/l`.
Move a window with `super + ctrl + h/j/k/l`.
![Alt text](docs/assets/move.gif)

Freely move a window with double tap super + h/j/k/l
Freely move a window from command mode, then use h/j/k/l.
![Alt text](docs/assets/free-move.gif)

Resize edges with `super + shift + h/j/k/l`.
Resize edges with `super + arrows`.
![Alt text](docs/assets/resize.gif)

Resize from the center with `super + alt + arrows`.

Show the [Command Overlay](#command-overlay) when the super key is held. Disable through command mode.
![Alt text](docs/assets/command_overlay.png)

Expand All @@ -69,14 +71,13 @@ Other
- `super + c` cycle through windows of the same app
- `super + shift + c` cycle through windows of the same app on the current desktop
- `super + .` screen search (click hints)
- `super + alt + h/l` switch to previous/next virtual desktop
- `super + alt + shift + h/l` move the active window to previous/next desktop (follow)
- `super + j/k` switch to next/previous virtual desktop
- `super + shift + j/k` move the active window to next/previous desktop (follow)
- `super + w` open Window Selector (fuzzy find open windows)
- `alt + h/l` move window focus left/right
- `alt + j/k` move window focus down/up (non-stacked)
- `alt + [` / `alt + ]` move window focus forward/back through stacked windows
- `super + alt + h/l` to move between desktops
- `super + shift + alt + h/l` send current tile to adjacent desktop
- `super + h/l` move window focus left/right
- `super + [` / `super + ]` move window focus forward/back through stacked windows
- `super + u/i` focus previous/next monitor
- `super + shift + u/i` move the active window to previous/next monitor

Enter Command Mode with `super + ;`.
- `r` to reload program/config
Expand Down Expand Up @@ -152,9 +153,39 @@ Add `debug = true` under `match.process_tree` to log process tree details to
| `super + m` | Maximize/un-maximize |
| `alt + q` | Close window |
| `super + Left/Right/Up/Down` | Resize window and snap to grids |
| `super + shift + h/j/k/l` | Resize centered |
| `super + ctrl + h/j/k/l` | Move window |
| `super` (double tap) | Toggle move mode |
| `super + alt + Left/Right/Up/Down` | Resize centered |
| `super + ctrl + h/j/k/l` | Move/snap window |
| `super + u/i` | Focus previous/next monitor |
| `super + shift + u/i` | Move window to previous/next monitor |
| `super + o` | Open native Task View overview |
| `window.super_double_tap_action = "overview"` | Optionally make double-super open native Task View overview |

When `modes.active = "carousel"` and `modes.carousel.enabled = true`, these key behaviors change:

| Shortcut | Action |
| --- | --- |
| `super + h/l` | Carousel focus left/right (current desktop + active monitor) |
| `super + shift + h/l` | Move carousel order left/right |
| `super + j/k` | Next/previous virtual desktop |
| `super + shift + j/k` | Move focused window to next/previous desktop |
| `super + space` | Center active tile on demand |
| `super + - / =` | Decrease/increase focused tile width |
| `super + o` | Open native Task View overview |
| `super + f` | Toggle desktop move follow behavior |

Carousel mode also maintains one trailing empty virtual desktop when
`modes.carousel.ensure_empty_desktop = true`.

The desktop status bar is globally enabled through `virtual_desktop.status_bar.enabled`.
Set `virtual_desktop.status_bar.show_in_non_carousel = true` to show it outside carousel mode too.
Carousel mode adds the current desktop's window strip using the appearance settings under
`modes.carousel.status_bar` such as `window_display`.
Status bar design inspiration: EngineeringMechanicsB's AHKVirtualDesktop project.

Carousel mode also does best-effort persistence for per-app tile width and strip order.
Order restore is keyed by `desktop:monitor` scope and app executable name, so it cannot
distinguish multiple windows from the same executable across restarts, and restore quality
can degrade when desktop indices or monitor numbering change.

#### Window management (Move mode)

Expand All @@ -163,27 +194,30 @@ Add `debug = true` under `match.process_tree` to log process tree details to
| `h/j/k/l` | Move window |
| `Esc` or `super` | Exit move mode |

#### Focus navigation (Alt)
#### Focus navigation

| Shortcut | Action |
| --- | --- |
| `alt + h/l` | Focus left/right |
| `alt + j/k` | Focus down/up |
| `alt + [` / `alt + ]` | Cycle stacked (prev/next) |
| `super + h/l` | Focus left/right |
| `super + [` / `super + ]` | Cycle stacked (prev/next) |

#### Virtual desktops

| Shortcut | Action |
| --- | --- |
| `super + alt + h/l` | Previous/next desktop |
| `super + j/k` | Next/previous desktop |
| `super + WheelUp/WheelDown` | Previous/next desktop (when `virtual_desktop.scroll_switch = true`) |
| `super + alt + shift + h/l` | Move window to previous/next desktop (follow) |
| `super + shift + j/k` | Move window to next/previous desktop (follow) |
| `super + alt + shift + WheelUp/WheelDown` | Move window to previous/next desktop (when `virtual_desktop.scroll_switch = true`) |
| `super + alt + <key>` | Go to mapped desktop (`[[virtual_desktop.<N>]]`) |
| `super + <key>` | Go to mapped desktop (`[[virtual_desktop.<N>]]`) |
| `super + alt + <key>` | Expel window to mapped desktop without following |
| `super + alt + shift + <key>` | Move window to mapped desktop (follow) |
| `virtual_desktop.fast_switch_non_carousel` | Skip the post-switch wait in non-carousel mode for faster desktop focus changes |
| `virtual_desktop.ensure_trailing_empty` | Keep exactly one trailing empty virtual desktop by creating and pruning as needed |
| `virtual_desktop.auto_assign` | Move newly created windows that match `apps[]` with `desktop` set |
| `virtual_desktop.debug_focus` | Log cross-desktop focus attempts to `%APPDATA%\harken\vd.focus.debug.log` |
| `virtual_desktop.switch_curtain` | Dim overlay during desktop switches to reduce flicker |
| `virtual_desktop.status_bar` | Global desktop status bar enablement; `show_in_non_carousel` extends it beyond carousel mode |

#### Apps (defaults)

Expand Down Expand Up @@ -282,7 +316,7 @@ GlazeWM is another popular tiling window manager for Windows operating systems.
| --- | --- | --- | --- | --- |
| Primary interaction model | Keyboard-first hotkeys and commands | Zone-based snapping (mouse + keyboard) | Dynamic tiling WM | Dynamic tiling WM |
| Launch-or-focus app hotkeys | Yes (configurable per app) | No (outside scope) | Possible via external tooling/scripts | Possible via external tooling/scripts |
| Directional focus movement | Yes (`alt + h/j/k/l`) | No | Yes | Yes |
| Directional focus movement | Yes (`super + h/l`) | No | Yes | Yes |
| Stack/window cycling | Yes (`super + [` / `super + ]`, app cycling) | Mostly | Yes (tiling containers/workspaces) | Yes (tiling containers/workspaces) |
| Virtual desktop hotkeys | Yes (native desktop integration) | Indirect (PowerToys + Windows shortcuts) | Yes | Yes |
| Freeform floating adjustments | Yes (move mode + resize controls) | Primarily zone snapping | Primarily tiling; floating is secondary | Primarily tiling; floating is secondary |
Expand Down
100 changes: 94 additions & 6 deletions config/config.example.toml
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,8 @@ send_keys = "^{Tab}"
resize_step = 20
move_step = 20
super_double_tap_ms = 300
# "overview" opens native Task View; "" disables double-super.
super_double_tap_action = ""

# Cycle app windows across all desktops.
cycle_app_windows_hotkey = "+c"
Expand Down Expand Up @@ -189,6 +191,8 @@ bottom = 5
enabled = true
switch_on_focus = true
ensure_count = 0
ensure_trailing_empty = true
fast_switch_non_carousel = true
cycle_prefer_current = true

# Optional mouse wheel switching (super+wheel).
Expand All @@ -201,12 +205,17 @@ enabled = true
opacity = 204
color = "#202020"

# Hotkey fields here use AHK syntax without super (super is implied).
# Modifiers are applied by Harken (alt or alt+shift) for desktop actions.
prev_hotkey = "h"
next_hotkey = "l"
move_prev_hotkey = "h"
move_next_hotkey = "l"
[virtual_desktop.status_bar]
enabled = true
# Show the desktop bar outside carousel mode too.
show_in_non_carousel = false

# Legacy super+alt desktop hotkeys are supported but disabled by default.
# The default workspace model uses super+j/k and super+shift+j/k instead.
prev_hotkey = ""
next_hotkey = ""
move_prev_hotkey = ""
move_next_hotkey = ""

# Debug logs write to %APPDATA%\harken when enabled.
debug_cycle = false
Expand All @@ -220,12 +229,23 @@ tray_format = "{current}/{total}"
# auto_assign = false
# auto_assign_interval_ms = 500

# Mapped desktop hotkeys use super+<key> for goto, super+alt+<key>
# for quick no-follow moves, and super+alt+shift+<key> to move and follow.
[[virtual_desktop.1]]
hotkey = "1"

[[virtual_desktop.2]]
hotkey = "2"

[[virtual_desktop.3]]
hotkey = "3"

[[virtual_desktop.4]]
hotkey = "4"

[[virtual_desktop.5]]
hotkey = "5"

# -------------------------------------------------------------
# Directional focus
# -------------------------------------------------------------
Expand All @@ -242,6 +262,74 @@ perpendicular_overlap_min = 0.2
cross_monitor = false
debug_enabled = false

# -------------------------------------------------------------
# Modes (optional)
# -------------------------------------------------------------

[modes]
# "carousel" enables niri-like horizontal focus/move behavior.
# Use "" to keep the default grid-oriented movement keys.
active = ""

[modes.carousel]
enabled = false
# niri-like default: do not auto-center on every focus change.
# Use super+space to center the active tile on demand.
auto_snap_center_on_focus = false
center_width_ratio = 0.5
side_width_ratio = 0.25
width_step = 0.05
gap_px = 12
wrap_enabled = false
include_minimized = false
excluded_apps = ["PowerToys.PowerLauncher.exe"]
# offscreen | stack_peek
overflow_policy = "offscreen"
# Keep tile sizes stable when focus changes.
resize_on_focus = false
# Skip tiny move/resize diffs to reduce jitter.
layout_epsilon_px = 8
# Keep focused tile away from hard viewport edges while scrolling.
scroll_reveal_margin_px = 80
ensure_empty_desktop = true
# Experimental: use native Windows API to reorder desktop indices.
native_desktop_reorder = false
# super+shift+j/k move-to-desktop follows focus when true.
desktop_move_follows_focus = true
focus_left_hotkey = "h"
focus_right_hotkey = "l"
move_left_hotkey = "+h"
move_right_hotkey = "+l"
desktop_prev_hotkey = "k"
desktop_next_hotkey = "j"
desktop_move_prev_hotkey = "+k"
desktop_move_next_hotkey = "+j"
desktop_reorder_up_hotkey = "^+k"
desktop_reorder_down_hotkey = "^+j"
overview_hotkey = "o"
center_hotkey = "Space"
width_decrease_hotkey = "-"
width_increase_hotkey = "="
toggle_follow_hotkey = "f"
debug_enabled = false

[modes.carousel.status_bar]
# top | bottom
position = "top"
height_px = 34
# Reserve extra pixels so carousel tiles do not sit under the bar.
reserve_gap_px = 4
# 0-255
opacity = 220
background_color = "#181818"
text_color = "#CCCCCC"
active_color = "#A020F0"
font_size = 10
# Max title characters per window in strip preview.
title_max_len = 26
# title | icon
window_display = "icon"

# -------------------------------------------------------------
# Focus border
# -------------------------------------------------------------
Expand Down
Loading
Loading