Add unified keybindings proposal for #198 (#210)

Proposes collapsing the multi-leader/multi-mode mess across zellij,
Ghostty, workmux, nvim, and the agent CLIs into a single scheme:

- One multiplexer (zellij owns panes/tabs; strip Ghostty's leader)
- Three-tier model: Super = OS, <leader> = mux, Space = editor
- zellij clear-defaults + one leader-entered mode (no mode soup)
- Seamless Alt+hjkl focus across zellij <-> nvim via
  vim-zellij-navigator
- Leader-key trade-off (Ctrl+Space recommended over Ctrl+a) so the
  agent CLIs keep their keys

RFC only; changes no live configs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SDzdtoy59UEWDZvZhZBkhB

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: binarypie

KEYBINDINGS.md

@@ -1,6 +1,30 @@
 # Keybindings Reference
 
-Hypercube uses consistent vim-style keybindings across all tools. This document provides a complete reference.
+Hypercube uses consistent vim-style keybindings across all tools. This document
+provides a complete reference.
+
+## The 3-tier model
+
+Hypercube spans a host desktop and the `devc` container, and your keystrokes pass
+through several programs at once. To avoid the "keyboard dance," keys follow one
+rule: **one modifier per layer, never overlapping.** You only ever reach for one
+of three things, and they live in different worlds:
+
+| Press | Talks to | Layer |
+|---|---|---|
+| **`Super` + …** | the OS | Hyprland windows & workspaces |
+| **`Ctrl+Space`** then a key | the multiplexer | zellij (inside `devc`): panes, tabs, sessions, agents |
+| **`Space` + …** | the editor | Neovim (LazyVim) |
+
+`Ctrl+Space` is a single **leader**: tap it to enter one mode, then press one key.
+There is no pane-mode vs tab-mode vs resize-mode to juggle. See
+[KEYBINDINGS-PROPOSAL.md](KEYBINDINGS-PROPOSAL.md) for the full rationale
+([#198](https://github.com/binarypie-dev/hypercube/issues/198)).
+
+> zellij owns multiplexing under the `Ctrl+Space` leader and Ghostty is a plain
+> renderer (no terminal leader). Within a tab, `Alt+hjkl` moves between zellij
+> panes; Neovim keeps its own `Ctrl+hjkl` for moving between its splits. The two
+> are intentionally separate — Neovim is the editor layer, zellij the mux layer.
 
 ## Hyprland Window Management
 
@@ -71,49 +95,94 @@ The **Super** key (Windows/Command key) is the main modifier.
 
 ## Ghostty Terminal
 
-Ghostty uses **Ctrl+A** as the leader key (similar to tmux/screen).
+Ghostty is a plain, chrome-less renderer. **Multiplexing — tabs, splits,
+panes — is owned by zellij** (see the next section), so Ghostty defines no
+terminal leader of its own. Dropping the old `Ctrl+A` prefix also frees it as
+readline "beginning of line" when you run `devc claude` in a plain window.
 
-### Tabs
+Ghostty keeps just two custom binds (plus its built-in copy/paste and
+scrollback defaults):
 
 | Keybinding | Action |
 |------------|--------|
-| `Ctrl+A, C` | New tab |
-| `Ctrl+A, N` | Next tab |
-| `Ctrl+A, P` | Previous tab |
-| `Ctrl+A, W` | Tab overview |
+| `Ctrl+Shift+N` | New window (for local console work outside the multiplexer) |
+| `Ctrl+Shift+,` | Reload config |
+| `Ctrl+Shift+C` / `V` | Copy / paste (Ghostty default) |
+
+---
+
+## zellij (devcube multiplexer)
+
+Inside `devc`, **zellij** is the terminal multiplexer — it manages your panes,
+tabs, and sessions, and each parallel agent (workmux worktree) is a zellij tab.
+
+The leader is **`Ctrl+Space`**. Tap it to enter **HYPER mode**, then press one
+key. Every key runs its action and returns to Normal, so it reads like a leader
+sequence — `Ctrl+Space |` splits, `Ctrl+Space c` makes a tab. There is only one
+mode to learn. `Esc` / `Enter` leaves HYPER mode.
 
-### Panes (Splits)
+### Panes
 
 | Keybinding | Action |
 |------------|--------|
-| `Ctrl+A, Shift+\` | Vertical split |
-| `Ctrl+A, -` | Horizontal split |
-| `Ctrl+A, X` | Close pane |
-| `Ctrl+A, Z` | Zoom/unzoom pane |
-| `Alt+F` | Toggle fullscreen pane |
-
-### Pane Navigation (Vim-style)
+| `Ctrl+Space` `\|` | Split right (vertical) |
+| `Ctrl+Space` `-` | Split down (horizontal) |
+| `Ctrl+Space` `n` | New pane |
+| `Ctrl+Space` `x` | Close pane |
+| `Ctrl+Space` `z` | Toggle zoom/fullscreen |
+| `Ctrl+Space` `w` | Toggle floating panes |
+| `Ctrl+Space` `e` | Embed / float pane |
+| `Ctrl+Space` `h/j/k/l` | Move focus |
+| `Ctrl+Space` `H/J/K/L` | Move the pane |
+
+### Tabs (workmux worktrees)
 
 | Keybinding | Action |
 |------------|--------|
-| `Ctrl+A, H` | Focus pane left |
-| `Ctrl+A, J` | Focus pane down |
-| `Ctrl+A, K` | Focus pane up |
-| `Ctrl+A, L` | Focus pane right |
+| `Ctrl+Space` `c` | New tab |
+| `Ctrl+Space` `[` / `]` | Previous / next tab |
+| `Ctrl+Space` `1`–`9` | Jump to tab _n_ |
+| `Ctrl+Space` `,` | Rename tab |
 
-### Pane Resizing
+### Resize, session, lock
 
 | Keybinding | Action |
 |------------|--------|
-| `Ctrl+A, R` | Enter resize mode |
-| Then `H/J/K/L` | Resize in direction |
+| `Ctrl+Space` `r` | Resize sub-mode (then `h/j/k/l` or `+`/`-`; `Esc` exits) |
+| `Ctrl+Space` `s` | Session manager |
+| `Ctrl+Space` `d` | Detach session (leave agents running) |
+| `Ctrl+Space` `q` | Quit — floating prompt: **Save** (resume on next `devc`), **Discard**, or **Cancel** |
+| `Ctrl+Space` `g` | Lock — pass every key to a focused TUI; `Ctrl+Space` again unlocks |
+
+### No leader needed
 
-### Other
+These work everywhere, no mode required:
 
 | Keybinding | Action |
 |------------|--------|
-| `Ctrl+A, [` | Enter copy mode (vim navigation) |
-| `Ctrl+A, Shift+R` | Reload config |
+| `Alt + h/j/k/l` | Move focus (hops between tabs at the edges) |
+| `Alt + =` / `Alt + -` | Grow / shrink pane |
+
+> `Alt+hjkl` moves between zellij **panes**. Inside Neovim, use Neovim's own
+> `Ctrl+hjkl` to move between **its** splits (see the Neovim section); the two
+> navigation layers are kept separate by design.
+
+---
+
+## workmux (parallel agents)
+
+[workmux](https://github.com/raine/workmux) orchestrates parallel agents on top of
+zellij: each `workmux add` creates a git worktree and opens it as **its own zellij
+tab** running the agent. So workmux has no separate keybindings — you navigate its
+worktrees with the zellij tab keys above (`Ctrl+Space [` / `]` or `Ctrl+Space 1-9`).
+
+| Command (run in any pane) | Action |
+|---|---|
+| `workmux add <branch> "<prompt>"` | New worktree + zellij tab running the agent |
+| `workmux list` | Show worktrees + agent status |
+| `workmux merge <branch>` | Merge and clean up |
+| `workmux remove <branch>` | Remove without merging |
+| `workmux dashboard` | Live control center (the default `devc` layout) |
 
 ---
 
@@ -196,11 +265,14 @@ Neovim uses LazyVim with **Space** as the leader key.
 
 | Keybinding | Action |
 |------------|--------|
-| `Ctrl+H/J/K/L` | Navigate windows |
+| `Ctrl+H/J/K/L` | Navigate Neovim windows |
 | `Space w` | Window menu |
 | `Space -` | Horizontal split |
 | `Space \|` | Vertical split |
 
+> `Ctrl+hjkl` moves between Neovim's own splits; `Alt+hjkl` moves between zellij
+> panes (see the zellij section). They're separate layers by design.
+
 ### Buffers
 
 | Keybinding | Action |

build_files/hypercube/03-hypercube-configs.sh

@@ -26,6 +26,12 @@ sed -i 's|^SHELL=.*|SHELL=/usr/bin/fish|' /etc/default/useradd 2>/dev/null || \
 # Starship config is read from STARSHIP_CONFIG env var set in fish config
 # Config lives at /usr/share/hypercube/config/starship/starship.toml (read-only)
 
+### zellij multiplexer - system default config
+# zellij doesn't honor XDG_CONFIG_DIRS (like fish), so its config can't live in
+# /usr/share/hypercube/config. Install the unified keymap as the system default
+# at /etc/zellij; users override it at ~/.config/zellij/config.kdl.
+install -Dm644 "${CONFIG_DIR}/zellij/config.kdl" /etc/zellij/config.kdl
+
 ### Ghostty terminal - stub that sources system config
 # Users can customize by adding settings after the config-file line
 mkdir -p /etc/skel/.config/ghostty

build_files/hypercube/99-tests.sh

@@ -47,6 +47,9 @@ REQUIRED_FILES=(
   "/etc/greetd/config.toml"
   # Config files
   "/etc/fish/config.fish"
+  "/etc/zellij/config.kdl"
+  # zellij ships as a static binary (not an rpm), so check the file directly
+  "/usr/bin/zellij"
   "/usr/share/hypercube/config/starship/starship.toml"
   # Theming
   "/usr/share/themes/Tokyonight-Dark/gtk-3.0/gtk.css"

build_files/hyprland/01-hyprland-desktop.sh

@@ -56,6 +56,22 @@ dnf5 -y install \
 ### Fish Shell (set as default)
 dnf5 -y install fish
 
+### Terminal multiplexer - zellij
+# zellij isn't packaged in the ublue/Fedora repos (`dnf install zellij` ->
+# "No match"), so install the official static musl binary. The base image is
+# amd64-only (no platform matrix in build.yml), so x86_64 is sufficient. Pinned
+# for reproducibility. Gives the host the same Ctrl+Space multiplexer keymap
+# (installed to /etc/zellij/config.kdl by 03-hypercube-configs.sh) as devcube.
+#
+# TODO(#198): a COPR spec now exists at packages/zellij/zellij.spec. Once the
+# `zellij` package is configured + built in the binarypie/hypercube COPR (already
+# enabled in base/01-base-system.sh), replace this block with `dnf5 -y install
+# zellij` and move the test in hypercube/99-tests.sh back to REQUIRED_PACKAGES.
+ZELLIJ_VERSION=0.44.3
+curl -fsSL "https://github.com/zellij-org/zellij/releases/download/v${ZELLIJ_VERSION}/zellij-x86_64-unknown-linux-musl.tar.gz" \
+  | tar -xz -C /usr/bin zellij
+chmod 0755 /usr/bin/zellij
+
 ### Terminal - Ghostty (from scottames COPR)
 dnf5 -y copr enable scottames/ghostty
 dnf5 -y install ghostty

dot_files/devcube/Containerfile

@@ -289,7 +289,17 @@ RUN fish_bin="$(command -v fish)" \
     && usermod --shell "$fish_bin" root
 
 # =============================================================================
-# LAYER 15: Entrypoint
+# LAYER 15: Session helpers
+# =============================================================================
+# devcube-session: the attach-or-create launcher the `devc` wrapper runs as the
+#   container command, so closing + reopening lands back in the same workspace.
+# zj-quit: the floating "Save / Discard / Cancel" quit prompt (Ctrl+Space q).
+COPY devcube/devcube-session.sh /usr/local/bin/devcube-session
+COPY devcube/zj-quit.sh /usr/local/bin/zj-quit
+RUN chmod +x /usr/local/bin/devcube-session /usr/local/bin/zj-quit
+
+# =============================================================================
+# LAYER 16: Entrypoint
 # =============================================================================
 COPY devcube/entrypoint.sh /usr/local/bin/devcube-entrypoint
 RUN chmod +x /usr/local/bin/devcube-entrypoint

dot_files/devcube/Justfile

@@ -75,6 +75,8 @@ test-build: build
     podman run --rm {{local_image}} workmux --version
     podman run --rm {{local_image}} starship --version
     podman run --rm {{local_image}} fish --version
+    # Session helpers must be on PATH and executable inside the container.
+    podman run --rm {{local_image}} sh -c 'command -v devcube-session && command -v zj-quit'
     # The entrypoint must pin $SHELL to fish so workmux drops new worktrees into
     # fish (its default-shell fallback is /bin/sh otherwise).
     podman run --rm {{local_image}} sh -c '[ "$SHELL" = "$(command -v fish)" ]'

dot_files/devcube/README.md

@@ -56,12 +56,31 @@ workmux merge <branch>            # merge and clean up
 workmux remove <branch>           # remove without merging
 ```
 
+Each `add` opens a new zellij **tab**, so switch between agents with the
+multiplexer leader: `Ctrl+Space` then `[` / `]` or `1`–`9`. zellij uses a single
+leader-entered mode for everything (panes, tabs, sessions) — full keymap in
+[KEYBINDINGS.md](../../KEYBINDINGS.md).
+
 Worktrees are created on a **per-project named volume** mounted at `/worktrees`,
 so they persist across restarts and stay isolated from other projects. The
 volume name is derived from the launch path, so `~/Code/myrepo` always gets the
 same worktrees back. (Worktrees live on the volume, not on the host — manage
 them from inside `devc`, not via `git worktree` on the host.)
 
+### Closing & resuming
+
+`Ctrl+Space q` opens a floating prompt to leave the devcube and drop back to your
+host shell:
+
+- **Save** keeps the session. zellij serializes it to the persisted home volume,
+  and the next `devc` from the same project reattaches to it — same tabs,
+  worktrees, panes, cwds, and scrollback.
+- **Discard** deletes the session, so the next `devc` starts fresh.
+- **Cancel** stays put.
+
+The session name is stable per project (derived from the launch path), which is
+what lets `devc` find and resume the saved session.
+
 ## How it works
 
 `scripts/devcube.sh` runs the image as an ephemeral `podman` container and mounts

dot_files/devcube/devcube-session.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# devcube-session — attach-or-create a named zellij session inside the container.
+#
+# Runs INSIDE the devcube container (the `devc` wrapper invokes it as the
+# container command), where the zellij sessions actually live. Given a stable
+# per-project session name it either:
+#
+#   * resurrects/reattaches an existing session of that name (one left behind by
+#     Ctrl+Space q -> Save, serialized under the persisted /root home volume), or
+#   * starts a fresh session with the requested layout when none exists.
+#
+# This is what makes "close the devcube, reopen it later, same workspace" work.
+#
+# Why not `zellij --session NAME --layout L`? With --session present, --layout is
+# interpreted as "add these tabs to the (not-yet-existing) session" and zellij
+# errors with "There is no active session!". The flag that always starts a fresh
+# named session with a layout is --new-session-with-layout, used below.
+set -euo pipefail
+
+session="$1"
+layout="${2:-}"
+
+# A session of this name already exists (running or serialized/resurrectable)?
+# `list-sessions` prints the name as the first field for both; awk matches it
+# exactly. With no sessions it errors to stderr (suppressed) and prints nothing.
+if zellij list-sessions --no-formatting 2>/dev/null |
+	awk -v s="$session" '$1 == s { found = 1 } END { exit !found }'; then
+	exec zellij attach "$session"
+elif [ -n "$layout" ]; then
+	exec zellij --session "$session" --new-session-with-layout "$layout"
+else
+	exec zellij --session "$session"
+fi

dot_files/devcube/scripts/devcube.sh

@@ -81,6 +81,12 @@ zellij | workmux)
 	slug="$(basename "$project_dir" | tr -c 'a-zA-Z0-9_.-' '-')"
 	phash="$(printf '%s' "$project_dir" | cksum | cut -d' ' -f1)"
 	wt_volume="${DEVCUBE_WT_PREFIX:-devcube-wt}-${slug}-${phash}"
+	# Stable, per-project zellij session name so closing the devcube (Ctrl+Space
+	# q -> Save) and reopening it resumes the SAME session. The home volume
+	# (/root) is shared across every project, so the name must be unique per
+	# project -> include phash. zellij session names can't contain '.', so the
+	# slug's dots are squashed to '-' (the volume name keeps them; it's separate).
+	session="devcube-$(printf '%s' "$slug" | tr '.' '-')-${phash}"
 	extra=(
 		# Worktrees live here (podman auto-creates the volume on first mount).
 		-v "${wt_volume}:/worktrees:rw"
@@ -89,15 +95,16 @@ zellij | workmux)
 		# isolated from other projects and survives restarts.
 		-e XDG_STATE_HOME=/worktrees/.local/state
 	)
-	# zellij 0.44.x fails ("There is no active session!") when --layout and
-	# --session are passed together, so we never combine them. The session name
-	# isn't load-bearing -- worktrees + workmux state persist via the volumes
-	# above, not the zellij session -- so we let zellij auto-name it. workmux
-	# operates on whatever the current session is, named or not.
+	# Hand off to the in-image launcher, which resurrects the named session if it
+	# exists (left by Ctrl+Space q -> Save) or creates it fresh otherwise. It has
+	# to run inside the container because that's where the sessions live, and it
+	# uses --new-session-with-layout (not --layout) to dodge zellij 0.44.x's
+	# "There is no active session!" when --layout is combined with --session.
+	# workmux operates on whatever the current session is.
 	if [ "$TOOL" = workmux ]; then
-		container_cmd=(zellij --layout workmux)
+		container_cmd=(devcube-session "$session" workmux)
 	else
-		container_cmd=(zellij)
+		container_cmd=(devcube-session "$session")
 	fi
 	;;
 esac

dot_files/devcube/zj-quit.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# zj-quit — the "quit devcube" prompt (bound to Ctrl+Space q in zellij).
+#
+# Launched in a floating zellij pane (see dot_files/zellij/config.kdl). It asks
+# whether to keep the session before dropping back to your host shell:
+#
+#   Save     -> Quit the session. With session_serialization on, zellij keeps it
+#               as a resurrectable session; the next `devc` reattaches to it
+#               (same tabs / worktrees / panes). See devcube-session.sh.
+#   Discard  -> Delete this session (and its serialized state) outright, so the
+#               next `devc` starts fresh from the workmux layout.
+#   Cancel   -> Close this prompt and stay where you are.
+#
+# The devcube image ships fzf, which renders the menu full-screen in the
+# floating pane — arrow keys / type-to-filter, Enter to pick, Esc to cancel.
+set -euo pipefail
+
+# zellij exports the live session name into every pane.
+session="${ZELLIJ_SESSION_NAME:-}"
+
+choice="$(
+	printf '%s\n' \
+		'Save     — keep this session; devc resumes it next time' \
+		'Discard  — delete this session; devc starts fresh next time' \
+		'Cancel   — stay here' |
+		fzf --reverse --no-info --cycle \
+			--pointer='▶' \
+			--prompt='quit devcube ▸ ' \
+			--header='Save your session before quitting?' ||
+		true
+)"
+
+case "$choice" in
+Save*)
+	# Quit -> resurrectable (serialization is enabled in config.kdl).
+	exec zellij action quit
+	;;
+Discard*)
+	# Kill the running session AND remove its serialized copy in one shot, so
+	# nothing is left to resurrect. Fall back to a plain quit if, for whatever
+	# reason, we don't know our own session name.
+	if [ -n "$session" ]; then
+		exec zellij delete-session "$session" --force
+	else
+		exec zellij action quit
+	fi
+	;;
+*)
+	# Cancel / Esc / empty — just close the floating pane.
+	exit 0
+	;;
+esac