linux-config/README.md

KM's Linux Desktop Config (chezmoi dotfiles)

This is my chezmoi-managed toolkit for keeping a consistent i3/terminal-focused Linux desktop across machines: i3 + i3blocks + i3bar, fish/Zsh/Bash shells, kitty/ST terminals, tmux, Neovim/Vim, Ranger, mpv, Zathura, dunst, picom, taskwarrior/taskopen, calcurse, Neomutt/msmtp, mgba, and a grab bag of helper scripts for wallpapers, audio, finance tickers, backups, etc. Other coding projects such as hands-free-tools, psa Arsenal, or kogito live in their own repos — this repo is solely about the desktop environment, shell tooling, and workflows that drive it.

Table of Contents

• What This Repo Is
• Installation & Sync
• Shells & Aliases
• Terminal & Editor Stack
• Window Manager & Display
• Productivity Apps & Services
• Scripts, Packages & Assets
• Host Overrides & Secrets
• Customization Tips

What This Repo Is

• A chezmoi repo with dot_* files targeting $HOME (e.g. dot_vimrc.tmpl → ~/.vimrc, dot_tmux.conf, dot_gitconfig.tmpl, etc.) and dot_config/** mirroring ~/.config. Every .tmpl file runs through chezmoi templating so {{ .chezmoi.hostname }} / .linux_os / .chezmoi.username can tailor behavior.
• A place for desktop-focused tooling: i3/i3blocks, fish
  • shared aliases, kitty/ST terminals, tmux, Neovim/Vim, mpv, Ranger, mpv, Zathura, dunst/picom/prefers, taskwarrior/taskopen, and shell helpers such as executable_passmenu, dmenu-history, change-sink, bg-chooser, etc.
• A repository for configuration logic only — the bulk of application/Project code lives in other repos. You can treat this as the “rice” layer for Arch/Ubuntu machines, not as a general diary of every coding sidequest.

Installation & Sync

1. Install chezmoi, clone this repo, and run chezmoi init --apply <repo> (or chezmoi cd . / chezmoi apply). The repo assumes you have a basic Linux desktop already (i3, fish, etc.).
2. Run chezmoi apply whenever you change templates. When files touch the ones under aliases/ (see below) run ~/scripts/sync-shortcuts (or let fish invoke it on login) to regenerate ~/aliases/.key_aliases, ~/.config/fish/key_abbr.fish, and ~/.config/ranger/key_mappings.conf.
3. After changing tmux config, reload (tmux source ~/.tmux.conf) and run the TPM installer (~/.tmux/plugins/tpm/bin/install_plugins).
4. When you edit dot_config/mgba/*.ini, run dot_config/mgba/update-mgba-config.fish (or your shell) to keep the ~/.config/mgba/*.ini copies and repo templates in sync.
5. Use chezmoi data set <key> <value> (or edit ~/.config/chezmoi/chezmoi.toml) to tweak host data such as gui, ext_kb, or linux_os — the template in dot_config/chezmoi/chezmoi-template.toml.tmpl seeds those values for conditional logic in templates.

Shells & Aliases

• dot_bashrc and dot_zshrc both source ~/aliases/.key_aliases and share settings like xset r rate, xmodmap tweaks, wal sequences, BASH_IT/oh-my-zsh hooks, and pywal colors so all interactive shells match.
• aliases/key_aliases.tmpl, aliases/key_dirs.tmpl, and aliases/key_files.tmpl are the canonical alias/directory/file lists. ~/scripts/sync-shortcuts consumes those to build shell-friendly alias files and ranger mappings; editing a key file there and rerunning that script keeps the shells/ranger in sync.
• Fish is the primary interactive shell (dot_config/fish/config.fish.tmpl). It sets spacefish prompt order, PNPM/GraalVM/Java paths, PASSWORD_STORE_CLIP_TIME, task abbrs, and automatically runs ~/scripts/sync-shortcuts plus source-ing every file in dot_config/fish/functions. That directory contains dozens of helpers: git helpers (git/g*), taskwarrior actions (task/*.fish), watson, timetrace, tmux-attach, pass/clipboard helpers, miniscripts for AWS/rsync, countdowns, currency converters, and more.
• dot_config/fish/completions adds completions for buku, kogito, kubectl, minikube, pass, timetrace, and watson so these workflows stay tab-complete.
• Fish also watches for logins without a $DISPLAY to auto-run startx, binds GPG_TTY, sources ~/.cache/wal/colors.sh, and respects host-specific values such as JENKINS_TOKEN (for NZXT) or ext_kb.

Terminal & Editor Stack

• dot_config/kitty/kitty.conf and dot_config/st/config.def.h.tmpl share wal colors (~/.cache/wal/colors-kitty.conf / colors-wal-st.h) and Nerd Font setups; kitty enables clipboard control and opacity, st pulls fonts/opacity from the current theme.
• Terminal multiplexer: dot_tmux.conf rebinds prefix to C-Space, enables mouse, uses a Powerline-style status bar, and installs TPM plugins (tmux-plugins/tpm, tmux-sensible, vim-tmux-navigator). Mouse/Vi copy mode maps push selection to xclip via copy-pipe-and-cancel.
• dot_vimrc.tmpl is the canonical Vim/Neovim config. It enables autoindent, autocommands for markdown/Go/Jenkinsfiles, loads vim-plug, and wires up plugins (YouCompleteMe, UltiSnips, vimtex, vim-fugitive, vim-auto-save, vim-instant-markdown, vim-tmux-navigator, vim-go, vim-react, vim-latex, vim-mark, vim-surround, rainbow, AutoPairs, vim-indexed-search, etc.). Leader mappings cover yanking, folding, Git, formatting, NERDTree, and quick plugin commands. dot_config/nvim/init.vim just sources ~/.vimrc plus Python host settings.
• dot_config/mpv/mpv.conf & input.conf configure subtitles, mouse wheel volume, speed keys, seek commands, zoom, and mark shortcuts for mpv so it works cleanly with keyboard/VR-style controls.

Window Manager & Display

• dot_xinitrc.tmpl loads ~/.Xresources, applies host-specific xmodmap (dot_Xmodmap*), sets redshift, xset r rate (pumped from fish), starts notification-daemon, picom, imwheel, numlockx, and pains wal -i $(scripts/shuffler ...) backgrounds.
• dot_Xresources.tmpl keeps host DPI/font choices (high DPI for x1-carbon, default for desktops), clickable URLs, transparency, and sxiv colors; i3blocks and kitty re-read it via xrdb + wal.
• There are multiple dot_Xmodmap* variants (., -laptop, -laptop-old, -old, -ubuntu, -vm) so xmodmap can swap Caps/Esc/backspace depending on host; dot_xinitrc.tmpl toggles between them via the ext_kb variable and the helper scripts/executable_xmodmap-custom.tmpl.
• dot_config/i3/config.tmpl wires up: Mod1/Mod4 split, kitty/urxvt terminals, i3 startup apps (notification daemon, picom, imwheel, wal, xbacklight), screenshot bindings, workspace assignments (1/2/3 etc), Slack/Signal/Chromium/Steam assignments, workspace navigation, passmenu, dmenu-history, ticker/fx shortcuts, redshift hotkeys, wal shuffle hotkeys, change-sink, and mod-based layout resizing. It also defines stacked/tabbed/floating rules, gap toggles, and bar outputs for both main and secondary monitors. The status command is i3blocks -vvv -c ~/.config/i3blocks/i3blocks.conf (primary) and i3blocks-secondary.conf (secondary) with i3blocks piping through ~/scripts/shuffler/pywal colors.
• dot_config/i3blocks/i3blocks.conf.tmpl defines blocks for kraken (ETH), Spotify controls, volume, and conditional blocks for laptop (battery, wifi, backlight), plus placeholders for dexscreener/ticker/memory/temperature. Secondary/ display configs reuse the same script directory but focus on calendar, volume, and additional temperature/name/cpu/memory blocks. Every block relies on scripts under dot_config/i3blocks/scripts/ (e.g. executable_calendar, executable_volume, executable_wifi, executable_kraken, executable_dexscreener*, executable_spotify, executable_name, executable_temperature, executable_ticker, etc.) which source ~/.cache/wal/colors.sh to stay on-theme.
• Display/notification stack also includes dot_config/picom/picom.conf (shadows/fade/opacity rules) and dot_config/dunst/dunstrc (compact, mouse-following notifications, keyboard shortcuts, urgency colors) so popups match the rest of the polished rice.
• dot_config/neofetch/config.conf keeps the neofetch info streamlined to kernel, terminal,font, shell, packages, WM, CPU/GPU, memory, disks, and resolution, with ASCII color blocks and shorthanded kernel/distro strings.

Productivity Apps & Services

• dot_taskrc configures taskwarrior (data location ~/.task, taskd server credentials, urgency coefficients per project/tag, and default context sniper). dot_taskopenrc tells taskopen to use nvim, the task binary, and custom note / annotation handling (notes.regex = "Notes").
• dot_qalcrc forces qalculate-gtk to use decimal commas for output. dot_inputrc turns readline vi mode on, and dot_imwheelrc remaps vertical scroll for imwheel.
• Ranger customization lives under dot_config/ranger/: rc.conf.tmpl tweaks view mode, preview pipeline (custom scope.sh), bookmarks, colors, and dozens of keybindings (vim-like navigation, copy/paste/paste symlink macros, fzf integrations, lightning bookmarks, backgrounds via wal, dragon drop, etc.). ranger/commands.py supplies fzf_select, fzf_locate, compress, extracthere, and other helper commands. Plugins include devicons, preview scripts, and shared key_mappings.conf (referenced at the bottom of rc.conf).
• Email is handled by dot_config/neomutt/neomuttrc pointing at ~/mail/firemail, calling msmtp, syncing (mbsync), and a custom <F5> macro. dot_config/msmtp/config defines a firemail account — replace the password with a secret manager or keep this file private (it currently contains a placeholder password).
• private_dot_calcurse/ stores Calcurse CalDAV configs/credentials and private_dot_gnupg/ holds GPG configs/keys; treat those as chezmoi private files (they live in private_dot_* in the repo and are decrypted on each machine). Similarly, dot_ssh/authorized_keys-all and known_hosts-all aggregate SSH entries for quick deployment.
• dot_config/zathura/zathurarc forces dark mode, custom colors, and clipboard syncing. dot_config/mgba/*-tmpl.ini keeps emulator settings; run dot_config/mgba/update-mgba-config.fish after editing your local ~/.config/mgba/*.ini so the template files stay current.
• dot_minikube/config/config.json fixes the driver to Docker ("driver": "docker").

Scripts, Packages & Assets

• The scripts/ directory hosts dozens of executable_* helpers that i3, fish, and launcher aliases depend on. Highlights:
  • executable_sync-shortcuts reads aliases/key_* and rewrites ~/aliases/.key_aliases, ~/.config/fish/key_abbr.fish, and ranger’s key_mappings.conf, keeping shells/ranger consistent.
  • Wallpaper helpers: executable_shuffler rolls a directory of backgrounds, executable_bg-chooser picks "bright"/"dim" sets through dmenu, and executable_dual-monitor-slideshow uses feh/ImageMagick to fill a single monitor while temporarily disabling others.
  • Audio/focus helpers: executable_change-sink reroutes Pulseaudio sinks, executable_ubuntu-start is an alternative startup script that replays imwheel/picom/wal, and executable_tex-clean deletes LaTeX build artefacts based on txt/tex-build-files.txt.
  • Productivity utilities: executable_passmenu wraps pass with dmenu, executable_dmenu-history keeps colorized dmenu launch history, executable_vim-man pops man pages inside Neovim, executable_currency hits frankfurter.app, executable_glhf-metadata queries an NFT API, and executable_ticker/executable_dexscreener*/executable_kraken feed price data to the i3blocks bar.
  • Misc scripts include executable_backup-pc (rsync/tar backups using exclude lists under txt/), executable_install-arch-pkgs.sh (installs from txt/pacman-pkgs/*.txt), executable_spotify-clean (VACUUM Spotify DB), and executable_spotify-now/dot_config/i3blocks/scripts/executable_spotify for play/pause+display via MPRIS.
  • scripts/colors/ contains playful ASCII color art used for celebrations or just curiosity.
• txt/ contains curated data:
  • txt/nzxt-pkgs.txt, txt/nzxt-aur.txt, txt/nzxt-all.txt, txt/nzxt-new.txt, txt/x1-carbon-pkgs.txt, txt/x1-carbon-aur.txt, txt/arch-2-pkgs.txt, txt/arch-2-aur.txt, and similar lists for Ubuntu/Termux packages.
  • txt/exclude-dirs-backup*.txt provide directory exclusions for backups.
  • txt/tex-build-files.txt enumerates LaTeX build extensions for executable_tex-clean.
  • txt/todo.md and txt/terminal-art.txt capture personal notes.
  • txt/usbs.md tracks mounted USBs.

Host Overrides & Secrets

• dot_config/chezmoi/chezmoi-template.toml.tmpl flags gui, ext_kb, and linux_os so templates can read host-specific values (e.g., ext_kb decides whether desktop laptops load .Xmodmap or .Xmodmap-laptop). Use chezmoi data set (or edit ~/.config/chezmoi/chezmoi.toml) to change these values per host.
• dot_Xresources.tmpl and dot_Xmodmap* swap DPI, fonts, and key remaps depending on the machine (x1-carbon vs nzxt vs vm). i3 bindings invoke xmodmap ~/.Xmodmap or the laptop variant depending on those template variables.
• private_dot_gnupg/ and private_dot_calcurse/ are chezmoi private directories — they contain real keys/certs and are not committed in plaintext. Keep them encrypted and use chezmoi add --private when tracking new secrets.
• dot_config/msmtp/config currently stores a password. In production, replace it with a pass-managed credential or environment variable, and never push secrets to a public repo.
• dot_taskrc embeds taskd credentials (host taskd.khkm.gq), so treat ~/.taskrc as private if you edit it, and sync it via chezmoi private mode if needed.
• dot_ssh/authorized_keys-all and known_hosts-all collect the SSH state that gets populated on every machine you chezmoi apply to.

Customization Tips

• Adding aliases/dirs/files: edit the aliases/key_* templates, then run ~/scripts/sync-shortcuts (or log in through fish and let the config run it) to regenerate shell aliases, fish abbrs, and ranger maps.
• Changing colors/backgrounds: the i3 config, dot_xinitrc, and scripts/executable_bg-chooser/shuffler call wal -i on directories under ~/Pictures/Backgrounds. Keep the structure and feh call in scripts/executable_dual-monitor-slideshow in sync when you add new folders.
• Updating mgba: edit your local ~/.config/mgba/config.ini/qt.ini, then run dot_config/mgba/update-mgba-config.fish to copy them back into the repo templates before committing.
• Updating i3blocks: the configs reference scripts under dot_config/i3blocks/scripts/. Editing or adding a script should maintain the command naming convention and the color/pywal sourcing shown in those scripts.
• Neovim tweaks: extend dot_vimrc.tmpl with new Plug entries; after editing, run nvim +PlugInstall +qall and keep the plugin list synchronized with init.vim sourcing the same file.
• Tmux tweaks: change dot_tmux.conf, then reload (tmux source-file) and reinstall packages via ~/.tmux/plugins/tpm/bin/install_plugins if you add TPM plugins.
• Taskwarrior contexts: dot_taskrc defines contexts (sniper, pey, mny, etc.) and urgency coefficients. Edit them if you rename project tags, then run task sync.
• Backup scripts: scripts/executable_backup-pc uses txt/exclude-dirs-backup*.txt, so update those lists whenever you add new directories to exclude from rsync/tar backups.
• Package installation: scripts/executable_install-arch-pkgs.sh reads txt/pacman-pkgs/*.txt. Keep that tree up to date before running the script.

Feel free to browse the scripts, dot_config/*, and txt/* files when you need to understand how a feature works — they are the single source of truth for this desktop’s automation.