Workspaces + Super+# + Super+Tab not working on ported machine: implementation guide, failure modes, verification

[nethum529]

Ground truth below is verified live on the source laptop (Hyprland 0.56.1, 2026-08-09). Read all of it before touching config — most failures come from misunderstanding where binds actually come from.

How keybinds/workspaces REALLY work here

There are THREE layers; none of them is hand-written binds in hyprland.conf:

1. Ambxst-generated binds (Super+#, workspaces, ~120 binds).
   Source of truth: ~/.config/ambxst/binds.json (stowed by this repo).
   The axctl daemon renders it into ~/.local/share/ambxst/hyprland.conf
   (verified: 49 workspace lines incl. bind = SUPER, 1, workspace, 1), which
   the main ~/.config/hypr/hyprland.conf sources at line ~102. That file also
   contains exec-once = ambxst, which starts the whole shell.
   No Ambxst ⇒ that file missing ⇒ almost no binds ⇒ 'workspaces broken'.
   parity/install-parity.sh seeds it (parity/ambxst/seed/) so binds work on
   the FIRST launch, before Ambxst regenerates it.

2. Super+Tab = hyprexpo plugin, not a bind.
   bind = $mod, Tab, hyprexpo:expo, toggle + a keyboard-nav submap in
   hyprland.conf. The hyprexpo:* dispatchers only exist when the plugin is
   loaded: hyprpm add https://github.com/sandwichfarm/hyprexpo (pinned
   upstream hash 7572889), hyprpm enable hyprexpo, and hyprland.conf already
   has exec-once = hyprpm reload -n.

3. Layout. The generated file sets general:layout = scrolling (native in
   Hyprland 0.56; verified hyprctl getoption general:layout → scrolling).
   Do not 'fix' it to dwindle — window behavior will feel wrong, though this
   is NOT what breaks workspace switching.

Correct implementation order

cd ~/linux-setup && git pull
./install.sh                  # stow (binds.json, hyprland.conf), packages, GPU
./parity/install-parity.sh    # Ambxst clone+patch+widgets, seed, hyprexpo, axctl
# then RELOG (not just hyprctl reload — exec-once only runs at session start)

Failure modes, most likely first

1. Parity layer never ran / ran before install.sh. The seed + Ambxst source
   are prerequisites for every bind. Symptom: ls ~/.local/share/ambxst/hyprland.conf → missing.
2. Seed skipped because the dir already existed. The installer only seeds
   when hyprland.conf is absent there. A half-broken previous attempt leaves
   a stale/empty dir. Fix: remove ~/.local/share/ambxst and re-run parity, or start Ambxst once (ambxst) so axctl regenerates.
3. Ambxst launches but dies instantly (missing quickshell, QML errors from a
   partial overlay copy). Check: pgrep -af 'qs -p' — the shell process is
   qs, NOT 'quickshell'; pgrep quickshell returning nothing is EXPECTED
   even when healthy. axctl daemon: pgrep -af 'axctl.*daemon'.
4. hyprexpo build failed. hyprpm compiles against headers; mismatched
   hyprland version or missing base-devel/cmake breaks it, and
   hyprpm reload -n (-n = no notify) hides the failure. Check
   hyprpm list → 'enabled: true', and hyprctl dispatch hyprexpo:expo toggle by hand.
5. Testing with hyprctl reload instead of relog. exec-once lines
   (ambxst, hyprpm reload) do NOT re-run on reload. Relog after changes.
6. Hand-editing generated files. Anything under ~/.local/share/ambxst/ is
   axctl output and gets rewritten; put changes in binds.json instead.
7. Different username. Seed files carry /home/nethum paths; the installer
   sed-rewrites them, but only on the seeding run (see mode 2).
8. Duplicate/conflicting binds added while debugging: hyprctl binds | grep -c 'SUPER, 1' should be 1.

Verify correctness (expected values from the working laptop)

hyprctl configerrors                          # empty
test -f ~/.local/share/ambxst/hyprland.conf && grep -c workspace ~/.local/share/ambxst/hyprland.conf   # ≈49
hyprctl binds | grep -c workspace             # ≈58 (dozens, not <10)
hyprctl binds | grep 'SUPER, 1' | head -2     # → workspace, 1
pgrep -af 'qs -p'                             # qs -p ~/.local/src/ambxst/shell.qml
pgrep -af 'axctl.*daemon'                     # axctl -c ~/.local/share/ambxst/axctl.toml daemon
hyprpm list                                   # hyprexpo enabled: true
hyprctl dispatch hyprexpo:expo toggle         # overview opens/closes
hyprctl getoption general:layout              # str: scrolling

Functional test: Super+2 switches workspace, bar numbers follow; Super+Tab opens the grid overview, arrows navigate, releasing Super confirms; Super+Comma opens the wallpaper picker (proves Ambxst IPC works end to end).

Note for whoever fixes docs: AGENTS.md's verify block says pgrep -a quickshell — wrong process name, should be pgrep -af 'qs -p'. Same fix applies here.

[nethum529]

Ran the full verification block on the ported machine (CachyOS, Hyprland 0.56.2) after install.sh + parity/install-parity.sh. 7 of 9 checks match the laptop. Reporting one failure mode the list doesn't cover, plus two bugs in the verification block itself.

Failure mode 9: seeded non-bind settings are destroyed on first regeneration

general:layout came out dwindle, not scrolling. This is not mode 2 (seeding skipped) — seeding worked correctly and was then overwritten.

Traced on 2026-08-09:

Location	Value
parity/ambxst/seed/hyprland.conf:13	layout = scrolling
parity/ambxst/seed/axctl.toml:27	layout = "scrolling"
live ~/.local/share/ambxst/hyprland.conf:13	layout = dwindle
live ~/.local/share/ambxst/axctl.toml:27	layout = "dwindle"

Root cause: Ambxst rewrites both generated files on every start from its own config, and that config has no layout key at all — grep -rn layout ~/.config/ambxst/config/*.json returns nothing, and the string scrolling appears nowhere under ~/.config/ambxst. So it falls back to its built-in default dwindle.

The asymmetry that makes this easy to miss: binds survive regeneration because they're backed by stowed binds.json. The layout is backed by nothing, so it's lost on the first regeneration and never comes back. Reseeding won't help — mode 2's fix (rm -rf ~/.local/share/ambxst and re-run parity) restores it only until Ambxst next starts.

Fix applied — an override in hyprland.conf, below the source line:

general {
    layout = scrolling
}

hyprctl getoption general:layout → str: scrolling, config errors empty, bind count unchanged.

Two bugs in the verification block

Check 9 can never pass. hyprctl binds | grep -c 'SUPER, 1' returns 0 on a fully healthy system. This hyprctl emits structured output — modmask: 64 and key: 1 on separate lines — so the literal string SUPER, 1 never appears. As written it cannot detect duplicate binds. Something like this works instead:

hyprctl binds | grep -A6 'modmask: 64$' | grep -c 'key: 1$'

Check 3's expected value looks stale. Block says hyprctl binds | grep -c workspace → ≈58, but this machine reports 48 loaded against 49 workspace lines in the generated file (check 2, which matched exactly). 48/49 is self-consistent, so ≈58 may predate a binds.json change.

Results

#	Check	Expected	Actual
1	configerrors	empty	empty
2	workspace lines in generated file	≈49	49
3	workspace binds loaded	≈58	48
4	SUPER,1 → workspace	present	present
5	qs -p …/shell.qml	running	running
6	axctl … daemon	running	running
7	hyprexpo	enabled: true	enabled: true
8	general:layout	scrolling	dwindle → fixed
9	duplicate SUPER, 1	1	0 (check is broken)

Docs note

AGENTS.md line 48 corrected from pgrep -a quickshell to pgrep -af 'qs -p', per the note at the end of this issue. Confirming the pitfall is real and expensive: I chased "the shell isn't running" for several steps on the strength of pgrep quickshell returning nothing, while qs was running the whole time.

[nethum529]

Correction to my previous comment: check 3's expected value of ≈58 is right — disregard my claim that it looked stale.

I measured 48 on a checkout that was 8 commits behind. home/.config/hypr/hyprland.conf on that revision had the static bind = $mod, 1..5, workspace, N / movetoworkspace block absent, so 10 workspace binds were simply missing. After pulling to ecf54a7, hyprctl binds | grep -c workspace reports 58, matching the laptop exactly.

My error: I treated a value measured on a stale checkout as evidence the documented expectation was wrong, instead of first verifying my tree was current. The other two points in that comment stand — failure mode 9 (seeded layout destroyed on regeneration) and the broken check 9 (grep -c 'SUPER, 1' returns 0 on a healthy system) were both measured on the current revision and still reproduce.