This guide walks you through setting up, configuring, and optimizing your Windows workstation with NREDF dotfiles, chezmoi, PowerShell 7, and aqua.
Open PowerShell (run as Administrator for service and package setups) and run:
irm https://raw.githubusercontent.com/NemesisRE/dotfiles/main/bootstrap.ps1 | iexOr using chezmoi directly:
# 1. Install PowerShell 7 and chezmoi (chezmoi runs every Windows hook under pwsh)
winget install Microsoft.PowerShell
winget install twpayne.chezmoi
# 2. Open a new terminal so both are on PATH, then initialize and apply dotfiles
chezmoi init --apply NemesisRE/dotfilesbootstrap.ps1 does the same, installing PowerShell 7 first when it is missing, because the hook that installs the other prerequisites is itself a PowerShell 7 script. The first apply installs aqua (the version pinned in aqua-bootstrap.yaml) and links its tools.
Chezmoi automatically manages and installs these core prerequisite packages on Windows via home/.chezmoidata/packages.yaml and winget during chezmoi apply.
If you prefer to install them manually upfront:
# Modern Shell & Terminal
winget install Microsoft.PowerShell
winget install Microsoft.WindowsTerminal
# Version Control
winget install Git.Git
# C/C++ Compiler for Neovim Tree-sitter
winget install LLVM.LLVM
# WSL OpenSSH Agent Bridge
winget install albertony.npiperelayTip
Font: this repo standardizes on FiraCode Nerd Font Mono everywhere (kitty, Konsole, Windows Terminal). On Linux and macOS it's installed automatically — Linux from a pinned, checksummed ryanoasis/nerd-fonts release archive, macOS from the font-fira-code-nerd-font Homebrew cask — but there is no winget package for it (DEVCOM.FiraCodeFont no longer exists in the winget-pkgs manifest tree). Install it by hand: download the FiraCode.zip asset from the pinned release (the version chezmoi installs on Linux/macOS is in .chezmoidata/nerd-fonts.yaml), extract it, select all the .ttf files, right-click → Install for all users. Then in Windows Terminal Settings (Ctrl+,) → Defaults → Appearance → Font face, set it to FiraCode Nerd Font Mono.
By default, NREDF uses safe defaults (false) and will not overwrite pre-existing Windows settings or system configurations. You can opt in during chezmoi init --prompt or by editing ~/.config/chezmoi/chezmoi.toml:
[data.windows.microsoftTerminal]
sync_settings = true # Sync Microsoft Terminal settings.json in AppData
[data.windows.winget]
sync_settings = true # Sync winget settings.json (telemetry off, rainbow bar)
[data.windows.wsl]
sync_config = true # Sync ~/.wslconfig (memory limits, mirrored networking)
memory = "16GB"
processors = 8
networking_mode = "mirrored"
nested_virtualization = false # Enable Hyper-V-based VMs inside WSL (true/false)
[data.windows.explorer]
apply_tweaks = true # Show file extensions, hidden files, compact mode
[data.windows.systemTweaks]
apply_tweaks = true # Developer Mode (unprivileged symlinks), Long Paths, UTC ClockNREDF supports multiple shells on Windows with shared aliases, history, and modern tool replacements:
- PowerShell 7+:
Documents\PowerShell\Microsoft.PowerShell_profile.ps1 - Windows PowerShell 5.1:
Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1(dot-sources PowerShell 7 profile) - 100% native CLI tooling:
fzf(Ctrl+t, Alt+c),lsd,bat,Atuinhistory search, andMenuComplete. - 5.1 limitation: the NREDF function library (Bitwarden session restore,
reload,NREDF_DailySync, etc.) needs PowerShell 7+ — one of its files uses the??operator, a parse error on 5.1 — so it is skipped there with a one-line warning. Everything else (aliases, prompt theme, tool init) still loads.
- WSL (Windows Subsystem for Linux): Full Linux environment running native Bash (ble.sh) or Zsh (Sheldon).
- Git Bash (MSYS2): Sources common NREDF shell libraries and aliases.
Switch between shells without restarting Windows Terminal:
reload -s pwsh # Reload into PowerShell 7
reload -s powershell # Switch to Windows PowerShell 5.1
reload -s bash # Switch to Git Bash / WSL Bash
reload -s cmd # Switch to Command PromptChezmoi automatically registers a scheduled task in Windows Task Scheduler:
- Task Name:
NREDF-DailySync - Trigger: Daily at 7:00 AM with
-StartWhenAvailable(automatically catches up when your PC turns on or wakes from sleep). - Settings:
-AllowStartIfOnBatteries -DontStopIfGoingOnBatteries. - Payload: Runs
NREDF_DailySyncin a non-interactive,-WindowStyle HiddenPowerShell process. - Tasks: Upgrades
chezmoi, pulls dotfiles updates, applies external templates, updatesaquatools, and vacuums old packages. - Log: Everything the run prints is appended to
$env:LOCALAPPDATA\nredf\daily-sync.log(a PowerShell transcript; rotated todaily-sync.log.1at 1 MB).
To check the task in PowerShell:
Get-ScheduledTask -TaskName 'NREDF-DailySync'To eliminate startup lag on Windows:
- Update Check Disabled:
$ENV:POWERSHELL_UPDATECHECK = 'Off'inDefaults.ps1suppresses slow remote GitHub release version polling on startup. - Profile Duration Banner Hidden:
"Microsoft.PowerShell:ShowProfileStartupDuration": falseinpowershell.config.jsondisables the native PowerShell startup timing banner. - Function Bundling: All 11 NREDF PowerShell functions are bundled into a single file during
chezmoi apply, loading in ~6 ms instead of ~100 ms.
| Shortcut | Action |
|---|---|
| Ctrl + Shift + t | Open new tab |
| Ctrl + Shift + w | Close active pane / tab |
| Alt + Shift + + | Split pane vertically |
| Alt + Shift + - | Split pane horizontally |
| Alt + ← / → / ↑ / ↓ | Move focus between split panes |
| Ctrl + Shift + f | Search terminal buffer |
| Ctrl + , | Open Settings UI |
| Shortcut | Function | Description |
|---|---|---|
| Tab | MenuComplete | Interactive terminal completion menu |
| Ctrl + r / ↑ | Atuin History | Interactive fuzzy history search across all your machines |
| Ctrl + t | fzf File Search | Fuzzy find files with syntax-highlighted bat preview |
| Alt + c | fzf CD | Fuzzy find directories with lsd --tree preview and jump |
| Ctrl + d | ViExit | Exit session if buffer is empty |
| Alt + d | ShellKillWord | Delete next word forward |
| Alt + Backspace | ShellBackwardKillWord | Delete previous word backward |
| Alt + q | SaveInHistory | Stash current line in history and clear buffer |
| " or ' | SmartInsertQuote | Automatically insert paired quotes and position cursor inside |
| → (Right Arrow) | Prediction Accept | Accept IntelliSense prediction candidate |
Bitwarden Desktop includes a built-in SSH Agent on Windows:
- Open Bitwarden Desktop → Settings → SSH Agent.
- Check Enable SSH Agent.
- Under Windows, Bitwarden exposes the OpenSSH named pipe:
\\.\pipe\openssh-ssh-agent. - The PowerShell profile automatically sets
$env:SSH_AUTH_SOCK = "\\.\pipe\openssh-ssh-agent". - Windows OpenSSH client and Git will automatically query Bitwarden for authentication without needing external SSH daemons.
Aqua manages cross-platform developer tools on Windows without needing separate Scoop or Chocolatey manifests:
| Tool | Purpose | Command |
|---|---|---|
| atuin | Shell history sync & fuzzy search | atuin |
| fzf | Interactive fuzzy finder | fzf |
| zoxide | Smart directory jumper | cd / z / zi |
| ripgrep | Fast recursive regex search | rg |
| bat | Syntax-highlighting cat (OneDarkPro) | bat |
| lsd | Modern file listing with icons | lsd |
| lazygit | Terminal Git UI | lazygit / lzg / lg |
| neovim | AstroNvim v6 editor | nvim |
| yazi | Terminal file manager | yazi / yy |
| lazydocker | Terminal Docker & Compose UI | lazydocker / lzd |
| lazyjournal | Multi-source log viewer & TUI | lazyjournal / lzj / lj |
| lnav | Advanced log file navigator & SQL analyzer | lnav |
| bottom | System resource monitor | btm |
| zellij | Builtin terminal workspace multiplexer | zellij |
Aqua tools are linked to %LOCALAPPDATA%\aquaproj-aqua\bin which is automatically added to PATH.
# Store GitHub token in system keyring for aqua downloads
aqua token setTip
You can automatically apply these tweaks by setting apply_tweaks = true under [data.windows.systemTweaks] and [data.windows.explorer] in ~/.config/chezmoi/chezmoi.toml.
To apply them manually upfront, run the commands below in an elevated (Administrator) PowerShell prompt.
Enabling Developer Mode allows chezmoi and git to create symbolic links without needing Administrator privileges:
reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock" /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"Prevents MAX_PATH (260 character) limits in deeply nested repositories (such as node_modules):
reg add "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /fIf you dual-boot Windows alongside Linux, Windows by default interprets the motherboard hardware clock as local time, causing time drift when switching OSes. Set Windows to use UTC:
reg add "HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\TimeZoneInformation" /v RealTimeIsUniversal /d 1 /t REG_DWORD /fRun yy in PowerShell to launch Yazi. Navigate directories with syntax previews, press q, and PowerShell automatically switches to that directory!
reload -pDisplays millisecond execution time for Oh-My-Posh, Atuin, PSFzf, and custom functions.
NREDF includes a smart sudo command that uses sudo.exe (Windows 11), gsudo, or an elevated process window:
sudo notepad C:\Windows\System32\drivers\etc\hostsBy default, Windows blocks script execution. Update your execution policy for your user account:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserIn Windows environments, your Documents folder may be redirected away from $HOME\Documents:
-
OneDrive Known Folder Move (e.g.
C:\Users\<user>\OneDrive\Documents):- PowerShell resolves
$PROFILEto the OneDrive path. - Chezmoi's post-apply hook (
.chezmoiscripts/run_onchange_after_windows_sync-profiles.ps1.tmpl) automatically creates NTFS directory junctions (PowerShellandWindowsPowerShell) pointing from OneDrive's Documents folder to$HOME\Documents\PowerShell.bootstrap.ps1runschezmoi init --apply, which triggers this same hook — it no longer carries its own separate copy of this logic. - The hook runs on the first apply and again only when the hook itself changes. If you move Documents later (e.g. turn on OneDrive Known Folder Move), re-run it with
chezmoi state delete-bucket --bucket=entryStatefollowed bychezmoi apply. - Directory junctions are local NTFS reparse points that do not require Administrator privileges.
- PowerShell resolves
-
Corporate Network / SMB Shares (e.g.
\\server\home$\<user>\Documentsor mapped driveH:\...):- NTFS junctions and remote symlinks cannot be created across network shares, and corporate file servers (FSRM) frequently block
.ps1scripts on network shares or trigger "Access is denied". - NREDF dotfiles automatically detect UNC / network paths and install an AllUsers profile trampoline into
$PROFILE.AllUsersCurrentHost(C:\Program Files\PowerShell\7\Microsoft.PowerShell_profile.ps1and Windows PowerShell 5.1). - This trampoline automatically sources your local profile (
$HOME\Documents\PowerShell\Microsoft.PowerShell_profile.ps1) before PowerShell evaluates the remote network profile. - Isolated UAC Elevation: If running unprivileged, the script requests standard UAC elevation solely to install the AllUsers trampoline files without elevating the rest of the dotfiles process.
- Non-Admin Fallback: If you lack administrator rights, you can configure your terminal to load your local profile directly:
- Windows Terminal (
settings.json):"commandline": "pwsh.exe -NoExit -Command \". '$env:USERPROFILE\\Documents\\PowerShell\\Microsoft.PowerShell_profile.ps1'\"" - VS Code (
settings.json):"terminal.integrated.profiles.windows": { "PowerShell": { "path": "pwsh.exe", "args": ["-NoExit", "-Command", ". '${env:USERPROFILE}\\Documents\\PowerShell\\Microsoft.PowerShell_profile.ps1'"] } }
- Windows Terminal (
- NTFS junctions and remote symlinks cannot be created across network shares, and corporate file servers (FSRM) frequently block
You can verify your active profile anytime:
$PROFILE | Format-List *Aqua: "remove a temporary file: The process cannot access the file because it is being used by another process" (WRN)
When running reload -d or installing packages on Windows, you may occasionally see a warning:
WRN remove a temporary file ... error="remove C:\Users\<user>\AppData\Local\Temp\<id>: The process cannot access the file because it is being used by another process."
Root Cause:
Microsoft Defender's real-time file scanner (MsMpEng.exe) immediately opens a read handle on newly unpacked .exe binaries in %TEMP% to verify their safety. When aqua finishes moving the executable into aquaproj-aqua\pkgs and attempts to delete the temporary extraction folder, Defender is still scanning the file, triggering a Windows sharing violation (ERROR_SHARING_VIOLATION).
Impact:
This is a non-fatal warning (WRN). The package extraction and installation is already complete and functional. The residual file in %TEMP% is automatically cleaned up by Windows Storage Sense.
Resolution:
To eliminate the warning and speed up package downloads, add an exclusion for aqua.exe in Microsoft Defender (run PowerShell as Administrator):
Add-MpPreference -ExclusionProcess "aqua.exe"
Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\aquaproj-aqua"1. "Cannot find file to detect the file's MIME type"
-
Root Cause: Yazi relies on the Unix
fileutility to detect file MIME types for previews and openers. On Windows,file.exeis distributed with Git for Windows (Git\usr\bin\file.exe). -
Resolution: NREDF automatically detects Git for Windows and exports
YAZI_FILE_ONEinDefaults.ps1as well as persisting it to the User environment duringchezmoi apply. If running Yazi outside of NREDF PowerShell, ensure Git is installed (winget install Git.Git) and set the user variable:[System.Environment]::SetEnvironmentVariable("YAZI_FILE_ONE", "C:\Program Files\Git\usr\bin\file.exe", "User")
2. Yazi Opens Files with VS Code Instead of Neovim
- Root Cause: On Windows, Yazi looks for configuration in
%APPDATA%\yazi\config\unless$env:YAZI_CONFIG_HOMEis set. Without this, Yazi ran with compiled-in preset defaults which map Windowsedittocode %s. - Resolution: NREDF automatically sets
YAZI_CONFIG_HOMEto$HOME\.config\yazi, creates a directory junction from%APPDATA%\yazi\configto$HOME\.config\yazi, and configures explicit[open]prepend rules inyazi.toml.tmplso all dotfiles (.*), source code, and text files route tonvim.
- Root Cause: On Windows, Zellij ignores both
~/.config/zellijandXDG_CONFIG_HOME. It only looks in%APPDATA%\Zellij\config\andC:\ProgramData\Zellij\, so it ran with built-in defaults instead of the deployedconfig.kdl, layouts and themes. - Resolution: NREDF sets
ZELLIJ_CONFIG_DIRto$HOME\.config\zellijinDefaults.ps1, persists it to the User environment (so Zellij started from Windows Terminal or Nushell picks it up after a new login), and creates a directory junction from%APPDATA%\Zellij\configto$HOME\.config\zellijas a fallback. If%APPDATA%\Zellij\configalready exists as an empty real directory (Zellij creates one on any run withoutZELLIJ_CONFIG_DIR), it is replaced by the junction; a non-empty one is left untouched and the environment variable still takes precedence.zclaudeadditionally passes its layout to Zellij as an absolute path and setsZELLIJ_CONFIG_DIRfor the Zellij it launches, so it works even from a shell that predates the variable. Check withzellij setup --check.
1. Chezmoi Pack: "attempt to concatenate a nil value"
- Root Cause:
astrocommunity.pack.chezmoiconcatenatesos.getenv "HOME" .. "/.local/share/chezmoi". Because Windows defaults toUSERPROFILErather thanHOME,HOMEwas unset (nil), causing a Lua runtime failure during lazy spec loading. - Resolution: NREDF automatically normalizes
vim.env.HOME = vim.env.USERPROFILEat the top of Neovim'sinit.lua, persists$env:HOME = $HOMEto Windows User environment variables, and points the chezmoi plugins at the source directory chezmoi itself renders (.chezmoi.sourceDir) inlua/plugins/chezmoi.lua.tmpl.
2. Mason: "Installation failed for ansible-lint: Platform not supported"
- Root Cause:
ansible-lintis an Ansible/Python CLI tool that requires POSIX APIs and does not natively support Windows. Mason's package registry explicitly restricts it tosupported_platforms: [unix]. - Resolution: NREDF filters
ansible-lintout of Mason's automatic installer on Windows inlua/plugins/mason.lua. The Ansible Language Server (ansible-language-servervia npm) and syntax highlighting continue to work on Windows, whileansible-lintis used when running in Linux/macOS/WSL.
chezmoi update # Pull latest dotfiles and apply
chezmoi edit Documents/PowerShell/Microsoft.PowerShell_profile.ps1 # Edit profile
aqua install # Update/install managed CLI tools
reload # Reload current PowerShell session- Unified Shells Guide (Zsh, Bash, Fish, Nushell, pwsh) — note: Fish has no Windows build; Nushell does
- Core Features & Tools Guide
- Dedicated Neovim Guide