Skip to content
skifliPublic

About

nixOS dots focused on keyboard-centric navigation

Resources

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

nixOS - An indubitably splendiferous configuration

NixOS Flakes Wayland License: MIT

Example image of my configuration in use!

Warning

The image above is very out of date. I'll update it when Ghostty blur lands in stable, but be aware a lot of changes have occurred since that picture was taken (whoops!)

A modular NixOS + Home Manager configuration which aims to, among other things, facilitate keyboard-centric navigation (every relevant option has an equivalent mouse control though as I'm also still learning)! It is easily extensible but comes with the following opinionated default setup:

  • A Wayland display server running the niri scrollable-tiling compositor, with auto-login via greetd.
  • Wayle as the unified desktop shell (handling bar, notifications, and the OSD).
  • Vicinae as the app launcher (an open-source launcher inspired by Raycast).
  • Ghostty with Zsh, Starship prompt, and Atuin history.
  • Helix as a TUI editor and Zed as a GUI editor.
  • Yazi as a TUI and Dolphin as a GUI file explorer.
  • A fully declarative Zen Browser configuration.
  • Automatic light/dark theme switching using Stylix and sunwait.
  • Secret encryption via Agenix.
  • And much, much more...

This is the configuration that started my NixOS journey, and it has stayed with me ever since. Therefore, there may be some anti-patterns, and non idiomatic ways of doing things in my configuration that go against how you should "Nix". However, the configuration has served me well over the more than a year straight that I have used Nix, and considering the fact that it has been the only distro I have not switched back to Windows after using, I am satisfied. Plus, the way I configured it at the start was with modularity in mind, so there is actually barely any technical debt when editing it - thanks past me :3!

Hosts

Hostname Architecture Graphics Notes
lyra x86_64-linux Intel CachyOS kernel.
fydetabduo aarch64-linux Panthor FydeTab Duo, uses fyde-nix hardware module.

Users

Username Description Default Shell Desktop Environment
ami Mah user zsh Niri + Wayle + Vicinae + Ghostty + Zen Browser
fynix FydeTab Duo user zsh Niri + Wayle + Vicinae + Foot + Zen Browser
rescue In case of kaboom user bash Fallback system user so none

Binary cache Build & cache

GitHub Actions builds the lyra and fydetabduo NixOS configurations and uploads their closures, including light/dark specialisations, to my self-hosted Xilo. The workflow also uploads the Anki Seara addon. Lyra uses GitHub's hosted x86_64 runner; FydeTab Duo uses the hosted ubuntu-24.04-arm runner.

GitHub workflows

My configuration also uses some other GitHub Actions located in .github/workflows/:

  • flake-checker.yml: Runs weekly checks on flake.lock health.
  • nix-build.yml: Builds lyra and fydetabduo (including available light/dark specialisations) and uploads their closures, plus the Anki Seara addon, to Xilo.
  • nix-maid.yml: Runs statix, deadnix, and alejandra on pushes/PRs, automatically opening a PR with the changes.
  • update-lockfile.yml: Scheduled weekly run (Sundays at 00:00) that automatically updates flake.lock and opens an automated PR.
  • dependabot.yml: Make sure the GitHub Actions dependencies are up to date, weekly.

Keyboard-centric workflow

A major goal of this config is being able to control as close as possible to everything from the keyboard without needing to constantly move my hand for the mouse (this is also made harder by the fact I don't have half a finger)!

The navigation layers

  1. Window & workspace level: Controlled via Niri (Mod + H/J/K/L and arrow keys).
  2. Standard GUI applications without Vim keys: Controlled via Kanata mouse emulation (Space held + E/S/D/F for movement, J/K/M for clicks).
  3. Screen grid: Controlled via waynav (Mod + ; followed by quadrant keys Q/W/A/S and Space to click).
  4. Web browser navigation: Controlled in Zen Browser via the Vimium-FF extension (f, F, d, u, gg, G).
  5. Files, shell, and clipboard: Via Ghostty, Yazi, and custom shell commands (copyl, blammo, $blammo_in).
  6. Global search and launching: Handled via Vicinae (Mod + D), Fuzzel, and custom layout scripts.

Kanata usage

Configured in users/programs/keyboard/kanata.nix, with the default / current configuration (which is in users/ami/variables.nix) being in a Lenovo Calliope UK ISO layout:

  • Activating mouse mode: Tap Space to type a normal space. Hold Space (longer than 250ms) to activate mouse mode.
  • Toggle lock: While in mouse mode, pressing n toggles mouse mode permanently ON so you don't have to keep holding space. Tap n again to unlock.
  • Left hand (movement and modifiers):
    • E / S / D / F: Move cursor Up / Left / Down / Right (with smooth acceleration).
    • A: Hold Shift (for shift-clicking or text selection).
    • G: Hold Ctrl (for multi-selection).
    • Q: Hold Super / Meta.
    • T: Hold Alt.
  • Right hand (clicks, scrolling, zoom):
    • J: Left click and drag (hold J while moving with E/S/D/F to drag-select).
    • K: Right click.
    • M: Middle click.
    • I / O: Scroll down / Scroll up.
    • W / R: Scroll left / Scroll right.
    • L: Hold for slow precision mode (movement set to 1px micro-steps).
    • U / P: Zoom in / Zoom out (Ctrl+= / Ctrl+- macros).

Waynav usage

Configured in users/programs/misc/waynav.nix.

Press Mod + ; (Super + Semicolon) to spawn a fullscreen overlay on the focused monitor:

Key / Keybinding Action Description
Mod + ; Activate waynav Spawns the fullscreen 2 by 2 overlay on the active output.
Q / W Top-left / Top-right Bisects the current target region into the upper quadrants.
A / S Bottom-left / Bottom-right Bisects the current target region into the lower quadrants.
G 3×3 grid mode Splits the active region into a 3 by 3 grid for finer selection.
H / J / K / L Vim nudge Micro-adjusts the target region left / down / up / right.
Space / Return Left click & exit Warps the cursor to the target center, left-clicks, and closes waynav.
D Double click & exit Warps and performs a double-click before exiting.
R Right click & exit Warps and performs a right-click before exiting.
M Middle click & exit Warps and performs a middle-click (e.g. to open links in new tabs).
Backspace History back Reverts the last bisection step.
Escape / ; Dismiss Closes the overlay immediately without clicking or warping.

Niri usage

Configured in users/programs/compositor/niri/binds.nix:

Focus and movement
Keybinding Action
Mod + H / Mod + Left Focus column left
Mod + L / Mod + Right Focus column right
Mod + J / Mod + Down Focus window down (in a vertical column)
Mod + K / Mod + Up Focus window up (in a vertical column)
Mod + Ctrl + J / Down Focus workspace down
Mod + Ctrl + K / Up Focus workspace up
Mod + 1 / Mod + Alt + H Focus left monitor (HDMI-A-2)
Mod + 2 / Mod + Alt + L Focus right monitor (DP-1)
Mod + Shift + 1 .. 8 Jump straight to workspace 1 through 8
Mod + Tab Smart overview (centers active workspaces)
Mod + Shift + Tab Standard overview toggle
Mod + A Interactive window switcher menu (window-switcher.sh)
Alt + Tab / Alt + Shift + Tab Next / previous recent window
Alt + grave Focus next window on the current monitor
Mod + Shift + H / Left Move column left
Mod + Shift + L / Right Move column right
Mod + Shift + J / Down Move window down in column
Mod + Shift + K / Up Move window up in column
Mod + Ctrl + Shift + J / Down Move column to workspace down
Mod + Ctrl + Shift + K / Up Move column to workspace up
Mod + Shift + Home / End Move column to first / last position
Mod + Comma / Mod + Period Consume window into column / Expel window from column
Mod + Alt + Shift + H/J/K/L Nudge floating window 10% in direction
Window sizing and column controls
Keybinding Action
Mod + W Toggle tabbed column view (stacks column vertically with tabs)
Mod + Equal (+) Increase column width (+10%)
Mod + Minus (-) Decrease column width (-10%)
Mod + C Center column
Mod + M Maximize column
Mod + F11 Toggle fullscreen
Mod + Shift + F11 Toggle windowed fullscreen
Mod + O Toggle window floating
Mod + R / Mod + Shift + R Cycle preset column widths (forward / back)
Mod + Ctrl + R / Shift Cycle preset window heights (forward / back)
App toggles (through find-or-make.sh)

The app toggle shortcuts will focus the application if already open, launch it if closed, or switch back to the previous window if the target is already focused (last one as per niri settings):

Keybinding Application
Mod + D Vicinae launcher
Mod + Return Ghostty terminal
Mod + Shift + Return Centered floating terminal (floating-term.sh)
Mod + ; Grid-based mouse navigator and warper (waynav)
Mod + F Dolphin file manager
Mod + Shift + F Yazi file manager
Mod + V Zed editor (zeditor)
Mod + E Helix editor (hx)
Mod + Shift + Z Zen Browser (zen-beta)
Mod + Shift + A Anytype
Mod + Shift + N Anki
Mod + Shift + C Ferdium
Mod + Shift + D TigerVNC viewer
Mod + Shift + Y Affinity suite
Mod + Shift + W Toggle Wayscriber screen annotation overlay (wayscriber)
Print Open LumineCapture screenshot editor (lumine-capture)
Shift + Print Full-screen screenshot, save + copy to clipboard (LumineCapture)
Ctrl + Print Region OCR via LumineCapture, save + copy (lumine-capture)
Alt + Print Monitor under pointer, save + copy to clipboard (LumineCapture)
Mod + Ctrl + D Toggle Do Not Disturb notifications (toggle-dnd)
Mod + Ctrl + L Toggle sleep inhibit
Ctrl + Shift + Escape Mission Center (system-monitor)
Shift + Escape Btop
Mod + N Todo and reminder manager (todo.sh)
Mod + Q Close focused window
Mod + Shift + Q Force kill current window (killcurrent)
Mod + Ctrl + Q Interactive click-to-kill window (killclick)
Mod + Alt + K Toggle on-screen keystroke overlay (wshowkeys)
Layout preset scripts
Keybinding Script Description
Mod + Ctrl + 1 1-niri.sh Default layout: Zen, Anki, Anytype, Ferdium, and TigerVNC arranged across both monitors.
Mod + Ctrl + 2 2-niri.sh NEA mode: Evince PDF, Zed editor, SyncTeX daemon, and Zen Browser.
Mod + Ctrl + 3 3-niri.sh F1iS mode: Affinity suite, Zen, Anytype, and Ferdium.
Mod + Ctrl + 4 4-niri.sh Anki focus mode: Stashes distraction apps into the scratchpad; places Anki on monitor 1, Zen and Anki Pomodoro on monitor 2.

Nirius usage

Configured using nirius:

Keybinding Action Description
Mod + P Toggle scratchpad Parks or unparks the focused window into the background scratchpad.
Mod + Shift + P Cycle scratchpad Cycles through parked scratchpad windows one by one.
Mod + Ctrl + P Toggle all scratchpad Shows or hides all scratchpad windows at once.
Mod + Alt + P List scratchpad Sends a desktop notification listing all parked scratchpad windows.
Mod + T Toggle mark Tags/untags the focused window with a mark.
Mod + Shift + T Focus marked Jumps straight to your marked window from anywhere.
Mod + Alt + T List marked Sends a desktop notification listing all marked windows.
Mod + Ctrl + F Toggle follow mode Makes the focused window follow along when changing workspaces.

Shell and clipboard scripts

Configured in users/programs/terminal-shell/zsh/initContent.sh:

  • copyl <file>: Converts any local path into a file:/// URI and copies it to the Wayland clipboard using wl-clipboard.
  • blammo and $blammo_in: When selecting files in Yazi (Mod + Shift + F) and suspending (Ctrl + Z) or quitting (q), Yazi saves the selected paths into /tmp/blammo. The Zsh prompt automatically loads this into $blammo_in so you can do things like copyl $blammo_in, ls -la $blammo_in, or run batch operations on the file selection.
  • safe_reboot: System shutdown or restart is auto blocked with a notification if a screen recording is active, a NixOS rebuild is running, or urgent windows need attention.
Nix and rebuild aliases (nh)

I use nh nearly all the time instead of raw nixos-rebuild commands:

Alias Command(s) Usage
nsw nh os switch Normal switch for daily config changes
nup nh os switch --update Updates all flake inputs and switches at once
ntest nh os test Temporary switch (back to previous on reboot)
nboot nh os boot Build and set as default for the next boot only
ndry nh os switch --dry Dry run with inbuilt nvd package diff
nask nh os switch --ask Shows visual package diff and prompts before switching
nvm nh os build-vm QEMU sandbox build to test bigger changes
nfc nix flake check --no-build Tests the flake syntax without building
ncl nh clean all --keep 5 Garbage collects old generations while keeping 5 safe
znsw z nixos && git pull && nh os switch Syncs repo changes and switches
znup z nixos && git pull && nh os switch -u Syncs repo changes, updates flake inputs, and switches
gfu git commit -m 'feat(flake.lock): update' ... Commit and push for updated lockfiles

User configuration and scripts

How scripts work across users

The configuration handles user scripts in three tiers:

  1. Shared scripts (users/common/scripts/): Common scripts used by all users, merged into ~/.local/bin/ using pkgs.symlinkJoin in users/default.nix. Includes niri-streamer.sh, todo.sh, schedule.sh, task-receiver.sh, and other workflow tools.
  2. Per-user scripts (users/<user>/scripts/): User-specific scripts, also merged via pkgs.symlinkJoin. Ami has 1-4-niri.sh layout scripts, anki-pomodoro.sh, niri_helpers.sh, and startup.sh. Fynix has only startup.sh.
  3. Inlined Nix scripts (userVars.shellScripts): Declared in each user's variables.nix and added to the user profile with pkgs.writeShellScriptBin (such as killclick, killcurrent, qrscan, qrcreate, and monitor focus helpers).

ami's custom scripts and tools

The majority of these are bound to Niri keybinds, or are user systemd services:

CLI task scripts
  • schedule.sh: A CLI task scheduler (inspired by axlefublr). You can queue commands from anywhere (schedule <command>), edit queued jobs in $EDITOR, check status (schedule ls), or look at stdout logs (schedule logs <id>).
  • task-receiver.sh: A background daemon that listens for pending tasks and runs them inside systemd-run --user --scope units. It listens to the Niri event stream to track spawned windows (like Ghostty), and if a task exits with an error, it opens a fuzzel dialog to retry, drop, or edit the command via vipe.
Niri related scripts
General scripts
  • emoji-picker.sh: A simple Fuzzel UI for quickly inserting a selected emoji into any application, using clipboard manipulation.
  • todo.sh: A TODO and reminder manager using fuzzel. It supports relative and absolute timestamps, on-boot reminders, and overdue tracking. It uses a systemd timer (--check) for periodic desktop notifications.
  • anki-pomodoro.sh: A 25/5 Pomodoro timer using termdown. It automatically toggles DND mode using wayle during focus rounds and un-mutes during breaks.
  • record.sh: A custom gpu-screen-recorder wrapper with region (slurp), portal, or monitor capture, and audio options. It includes a post-recording menu to compress with FFmpeg (H.265), copy to clipboard, delete, and / or open the folder.
  • smart-rebuild.sh: Spawns a floating terminal, pulls git updates, updates submodules, switches the NixOS flake with some custom limits, logs execution time, and can reboot or powers off after.
  • theme-switcher.sh: For when I want to manually switch between light and dark system specialisations using sudo switch-to-configuration test so it doesn't clutter the bootloader generations.
  • autoclicker.sh: A script that uses ydotool with preset speed modes (50ms, anti-AFK, 100-click bursts, or custom intervals).
  • view-clipboard-image.sh: Quickly opens the copied image or file URI in swayimg.
  • rdp.sh: Another fuzzel launcher for TigerVNC VNC connections to remote machines using credentials from Agenix.

(Some) available program options

More are available (that I've added myself to the code but not the below concise list), but these are the main ones. And it is, of course, trivial to add your own.

Important

Values are the file name without .nix.

Desktop session
Key in userVars.programs Available values Upstream
compositor niri niri
desktop-shell wayle Wayle
display-server wayland Wayland
idler swayidle swayidle
keyboard kanata Kanata
killer earlyoom earlyoom
launcher vicinae Vicinae
login-manager greetd greetd
nightlight sunsetr sunsetr
Apps and tools
Key in userVars.programs Available values Upstream
browsers (list) zen-beta Zen Browser, BrowserOS
editor hx Helix
ergonomics safeeyes Safe Eyes
explorer-gui dolphin, nemo Dolphin, Nemo
explorer-tui yazi Yazi
network-mounts nfs NFS remote mount automation
pager ov ov
partition-manager kde KDE Partition Manager
remote-desktop vnc, remmina TigerVNC, Remmina
screen-recorder gpu-screen-recorder GPU Screen Recorder
system-monitor missioncenter Mission Center
vpn tailscale Tailscale
Shell and prompt
Key in userVars.programs Available values Upstream
terminal ghostty Ghostty
terminal-shell zsh Zsh
prompt starship Starship
visual zeditor Zed
Extra modules (under programs.other)

These modules are under users/programs/misc/ and can be enabled by adding their name to the programs.other list in variables.nix:

  • affinity - Serif Affinity suite.
  • anki - Spaced repetition flashcard software with custom add-ons & FSRS.
  • atuin - Shell history sync and daemon search.
  • aw - ActivityWatch automated time tracking & watchers.
  • kde-connect - Device synchronization & clipboard integration.
  • nix-direnv - Fast per-directory Nix devenvs.
  • nix-index-database - Fast binary search & comma (nix-index) integration.
  • nix-your-shell - Consistent subshell environments.
  • opentabletdriver - Open source graphics tablet driver & daemon.
  • rnote - Sketch & handwritten notes (fynix only).
  • steam - Steam with Proton-GE & GameMode support.
  • styles - System-wide base16 theming, GTK/Qt synchronization, & daemon for the auto theme switching!
  • typst - Fast markup-based typesetting system.
  • waynav - Wayland-native grid bisector and pointer navigation tool.
  • wayscriber - ZoomIt-style live screen annotation daemon (toggled with Mod + Shift + W).
  • wl-clip-persist - Persistent clipboard - prevents copied text loss on app close.
  • wshowkeys - On-screen keystroke, modifier, and mouse click visualizer for Wayland.
  • ydotool - Wayland-compatible CLI for automated inputs.

The dolphin module also bundles the Linux File Converter Addon, adding a "Convert to..." action to Dolphin's right-click menu. Its Python dependencies are packaged (no pip/venv), automatic self-updates are disabled, and the modern UI is built from source so it works on both x86_64 and aarch64.

Screenshots

TODO: Add screenshots or desktop previews here later :).

Inspirations and credits

Just wanted to dedicate a section to thank the other amazing FOSS configs, and people, whose work inspired or directly helped parts of this setup 🩷:

  • axlefublr: For inspiring the task scheduler setup, along with a bunch of shell concepts and ideas for my workflow.
  • MangoCubes: For inspiring the inlined Nix shell scripts and several neat Niri binding helpers (like killclick, killcurrent, and qrscan).
  • YaLTeR: For creating Niri, the best compositor I've ever used.
  • BANanaD3V & sodiboo: For the fantastic Niri flakes.
  • tsdh: For nirius, which provides a wide bunch of extremely useful utilities for Niri - definitely saved me a lot of manual scripting!
  • 0xc000022070: For making an incredible zen-browser-flake, and happily responding to my various comments and issues.
  • rodrada: For making an Anki addon which makes it responsively follow system theme, and even packaging it as a Nix flake :o!
  • And many more which I have most definitely forgotten to put here 😅.

About

nixOS dots focused on keyboard-centric navigation

Resources

Stars

3 stars

Watchers

0 watching

Forks

Contributors

Languages