Home Modules¶
Home-manager modules live in modules/home/. Each is exposed as flake.homeModules.<name>.
Available Modules¶
| Module | Flake output | Description |
|---|---|---|
| base | homeModules.default |
Base home: shell, editor, ssh, fonts, nix-index |
| shell | homeModules.shell |
zsh, tmux, fzf, starship, git, bat, btop, direnv, eza, zoxide, jq, sesh, aliases, android |
| editor | homeModules.editor |
Helix, nvix (Neovim) |
| ai | homeModules.ai |
opencode, claude, mcp, pi, providers (anthropic, office, zen, openrouter) |
| browser | homeModules.browser |
Zen browser (base, extensions, keymaps, search) |
| terminal | homeModules.terminal |
kitty terminal |
| hyprland | homeModules.hyprland |
Hyprland home config, rofi, hypridle, hyprlock, keymaps |
| darwin | homeModules.darwin |
aerospace, karabiner, hammerspoon, jankyborders |
| stylix | homeModules.stylix |
Stylix theming (config + cli-only mode) |
| packages | homeModules.packages |
GUI packages + nixcord (not meant for external use) |
| syncthing | homeModules.syncthing |
Cross-device file sync |
| sops | homeModules.sops |
Home-level sops secrets |
| ssh | homeModules.ssh |
SSH client config + agent |
| naste | homeModules.naste |
naste CLI client (endpoint pre-configured) |
| mpv | homeModules.mpv |
Media player with modernx OSC |
| zathura | homeModules.zathura |
PDF/document viewer |
| aria2 | homeModules.aria2 |
aria2 download manager |
| nix-index | homeModules.nix-index |
, command (run unknown binaries) |
| nix-conf-fix | homeModules.nix-conf-fix |
Fix attic's bare substituters in user nix.conf |
| home-only | homeModules.home-only |
For standalone home-manager (adds flakeModules.nix) |
Importing¶
{ flake, ... }: {
imports = [
flake.homeModules.default # shell, editor, ssh, fonts
flake.homeModules.ai # AI tooling
flake.homeModules.stylix # theming
];
}
In NixOS/Darwin hosts
When used inside a NixOS or Darwin host, home modules are added via home-manager.sharedModules. The NixOS default.nix and Darwin sharedModules.nix wire this automatically.
Design Philosophy¶
A few deliberate choices repeat across these modules. They explain the per-module details below:
- vi-mode / hjkl everywhere - zsh, tmux, kitty, hyprland, mpv, zathura, rofi, aerospace, and skhd share the same motion keys. One muscle memory set works across shell, terminal, window manager, and media apps.
jkescape - the same escape chord in zsh, opencode, pi, and Hammerspoon's system-wide vim mode. Leaving insert mode is identical everywhere.- OSC52 clipboard - visual yank reaches the local clipboard over SSH and inside tmux, with no xclip forwarding or extra config.
- Shared stylix theme - kanagawa-dragon colors and Monaspace fonts flow from NixOS to Darwin to home-manager, so every app reads the same theme - no per-app configuration.
- nix-wire auto-import - drop a
.nixinto a module directory and it's wired automatically. That's whyshell/,editor/,ai/, etc. are directories with adefault.nixthat imports its siblings - no import list to maintain.
base.nix - default.nix¶
The base home setup every user gets - the foundation all other home modules layer on. Platform-agnostic on purpose: one module works on NixOS, Darwin, and standalone home-manager, so there's no per-OS fork of the common user environment.
What it does:
- Sets
home.stateVersion = "26.05" - Enables fontconfig
- Imports:
shell,editor,ssh,nix-index,aria2,nix-conf-fix - Installs fonts: noto (sans, emoji, CJK), carlito, ipafont, kochi-substitute, source-code-pro, dejavu, nerd-fonts (jetbrains-mono, fira-code, droid-sans-mono)
Usage:
shell¶
Auto-imported directory (modules/home/shell/). Import via homeModules.shell.
default.nix¶
The shell bundle - everything that makes the terminal usable. Adding foo.nix here wires it automatically (no import list to touch); nix-your-shell so nix-shell -p works inside zsh.
- Imports all shell sub-modules via
nix-wire.lib.autoImport - Enables
nix-your-shell - Installs:
devenv,nixpkgs-track,nixpkgs-manual,nixpkgs-review,nh,duf
zsh.nix¶
Zsh as the primary shell, configured so editor muscle memory carries over and the clipboard works remotely. vi-mode + jk escape match the editor/tmux chords; OSC52 so visual yank reaches the local clipboard over SSH and tmux; fzf-tab so completion is fuzzy instead of prefix-only.
zsh-vi-modeplugin (escape withjk)zsh-fzf-tabplugin (Alt+j/Alt+kcomplete)- Autosuggestions + syntax highlighting
- OSC52 copy integration (visual yank → clipboard, works over SSH/tmux)
runbgfunction (resume a Ctrl+Z'd job in background)- Sources
~/.temp.zshif it exists
tmux.nix¶
Tmux as the session/pane layer, kept consistent with the shell and editor. Vi mode for hjkl navigation; Ctrl+a prefix (easier to reach than the default Ctrl+b); OSC52 copy so yanks work over SSH without xclip forwarding; minimal status line so panes get the screen space.
baseIndex = 1,keyMode = "vi",shortcut = "a"(prefix isCtrl+a)- Plugins:
minimal-tmux-status,better-mouse-mode,fzf-tmux-url(u),vim-tmux-navigator - OSC52 copy via the
copytool in fzf-url ta <session>command (attach/create session)Ctrl+eedits pane output in$EDITOR- Undercurl support, true color, extended keys
- Splits:
|horizontal,-vertical,v/s(open in cwd)
fzf.nix¶
Fzf as the universal fuzzy picker, wired into shell, tmux, and git. fd replaces find (faster, respects gitignore by default); ripgrep powers preview content search.
- Default options: 60% height, reverse layout, highlight line, custom colors
fdas the file finder (hidden, follow symlinks)fzf-previewfor previewsnix-search-tvpackage (fuzzy nixpkgs search)Ctrl+Rhistory,Ctrl+Spaceaccept autosuggestion (wired in zsh init; requires reassigning macOS input source shortcut away from Ctrl+Space + reboot)fzfpalias for fzf with preview
starship.nix¶
Custom starship prompt that surfaces git state and dev-shell context at a glance. Two-line so the verbose git info (branch, last commit, status counts) sits on its own line and never eats into the command line.
- Shows: directory icon, file count, folder count, disk usage
- Git: branch, host icon (github/gitlab/etc), last commit message, status with counts
- Two-line prompt (git info on second line)
- Vim mode character (
vimcmd_symbol) - Nix shell state indicator (impure/pure/unknown)
git.nix¶
Git with the surrounding tooling (gh, lazygit) and defaults that keep history clean and resolvable. pull.rebase for linear history; diff3 conflict style so the original context is visible during merges; rerere so repeated conflicts auto-resolve.
pull.rebase = true,merge.conflictStyle = "diff3",rerere.enabledinit.defaultBranch = "master",core.editor = "nvim"ghwithgh-notifyextensionlazygitwith nvim-remote edit preset, OSC52 clipboardgfm <branch> [remote]helper (fetch + merge)git-addnospacealias (stage ignoring whitespace)- Git maintenance enabled for
~/work/nixpkgs
bat.nix¶
cat replacement that adds syntax highlighting and line numbers for free. Aliased so cat muscle memory carries over - pipe to it or read a file, same invocation.
batenabledcataliased tobat --paging=never --style=plain
btop.nix¶
top/htop replacement, configured with vim keys so you navigate processes with hjkl - same motions as the shell and editor.
btopwithvim_keys = true, transparent background
direnv.nix¶
Auto-loads the nix dev shell when you cd into a project, so there's no manual nix-shell/nix develop per visit. nix-direnv keeps the shell cached (fast reloads).
direnv+nix-direnv, silent, zsh integration
eza.nix¶
ls replacement that adds git status per file, icons, and colors. Aliased onto ls/lt so the same muscle memory gives a richer view with zero retraining.
ezawith colors, git, icons, group/header/smart-group- Aliases:
ls→eza -s modified --reverse,lt/tree→ tree view
zoxide.nix¶
cd replacement that learns your frequent directories - cd proj jumps to the right one instead of typing the full path. Bound as cd directly; /nix excluded because store paths aren't useful jump targets.
zoxidewith--cmd cd(replacescdwith zoxide)- Excludes
/nix
jq.nix¶
JSON CLI. Enabled so it's on PATH and available to the fzf/nsearch tooling above for ad-hoc JSON inspection.
jqenabled
sesh.nix¶
sesh tmux session manager - so you don't recreate the same sessions every time you switch projects. Predefined sessions (todo, notes, LeetCode, main) mean one keystroke opens the full workflow.
- Pinned to v2.25.0 (overridden hash)
tmuxKey = "c-o"(open sesh from tmux)- Predefined sessions:
todo(opens todo.md in nvim),notes(ObsidianQuickSwitch),LeetCode(Leet command),main - Blacklist: scratch, Library, Applications, Pictures
Ctrl+pin tmux →sesh last
aliases.nix¶
Shell aliases + the nxbuild helper. nxbuild exists to offload nix builds to remote machines (semi/dsd) so the local machine doesn't melt - the rest are shortening aliases (c, d, colored cp/rm) and a help that pipes through bat.
- Aliases:
c(clear),d(background),cp/rm/rcp(colored/verbose),mkdir -pv,isodate,matrix,fetch(fastfetch),font-family helpcommand (pipes--helpthrough bat)nxbuild- build nix packages on remote builders. Usage:
android.nix¶
Android device tooling: android-tools for adb/fastboot, scrcpy for low-latency screen mirroring and control over USB.
- Installs
android-tools+scrcpy
Usage:
editor¶
Auto-imported directory (modules/home/editor/). Import via homeModules.editor.
helix.nix¶
A second editor alongside nvix. Relative line numbers so 5j/3k motions stay accurate; LSP messages surfaced inline.
helixwith relative line numbers, LSP display messages
nvix/default.nix¶
Neovim via the nvix flake. Exposes an option:
| Option | Type | Default | Description |
|---|---|---|---|
nvix.variant |
enum ["bare" "core" "full"] |
"core" |
Which nvix variant to install |
- Sets
EDITOR = "nvim",vimAlias = true - Codesnap watermark font set to CaskaydiaCove
- Colorscheme: catppuccin disabled (kanagawa-dragon used via stylix instead)
Usage:
{ flake, ... }: {
imports = [ flake.homeModules.editor ];
nvix.variant = "full"; # or "bare" for minimal
}
ISO uses bare
The installer ISO forces nvix.variant = "bare" to keep the image small.
ai¶
Auto-imported directory (modules/home/ai/), excluding combined-system-prompt.nix (a helper). Import via homeModules.ai.
Sets CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS = 1 globally.
opencode/¶
Opencode agent configuration.
- Package:
pkgs.opencode-vim(patched node_modules hash + bun version check bypass) - Plugin: ponytail (lazy dev skill, toggleable via
/ponytail) - TUI: vim system clipboard,
jkescape, enter-to-submit, insert-after-submit - Agent: oh-my-openagent (Sisyphus) is the sole agent system; no external agent registry
- System rules: written to
~/.config/opencode/AGENTS.mdfromsystem-prompts/(applies to every agent globally) - Skills: wired from three sources - local (
skills/), ponytail flake, claude-code flake (frontend-design) - Auto-imports siblings: drop a new
.nixinopencode/to add config (agents.nix, providers/*)
agents.nix¶
Agent config for the oh-my-openagent plugin.
default_agent = "sisyphus"(oh-my-openagent provides the agent system + subagents: explore, librarian, oracle, metis, momus, etc.)- Commit hygiene prompt: never set
--authoror addCo-authored-bytrailers for the AI agent
claude.nix¶
programs.claude-code.enable+ MCP integration- Vim mode, model
claude-opus-4-6,ENABLE_TOOL_SEARCH = true ~/.claude/CLAUDE.mdset to the combined system prompt
mcp.nix¶
MCP (Model Context Protocol) servers. Opencode spawns every configured server as a child process on startup, so only universally-needed servers are included globally. Work-specific servers are gated behind an option.
| Server | When included | Purpose |
|---|---|---|
git |
Always | Git MCP server |
fetch |
Always | Fetch MCP server |
github |
Work hosts only | GitHub API (needs GITHUB_TOKEN) |
gitnexus |
Work hosts only | Code knowledge graph |
newton-hs-prod |
Work hosts only | Juspay internal code search |
bitbucket |
Workstation hosts (via workstation.nix) |
Bitbucket Server API |
Removed from global config (were spawning node processes on every launch): playwright, sequential-thinking, everything (filesystem - opencode has its own file tools), deepwiki, nixos. Add these per-project if needed.
Option: ndots.ai.mcp.workServers - when true, work-tier servers (github, gitnexus, newton-hs-prod) are included. Enabled on work hosts (dsd, semi, jp-mbp, mach).
pi.nix¶
Pi coding agent (via llm-agents).
- Default provider: anthropic, thinking level: medium
vim-motions-pipackage withjkescape + OSC52 clipboard- Packages: nodejs, bun, copy
- System prompt: combined system prompt
providers/¶
Auto-imported directory of opencode provider definitions. One file per provider, drop a new .nix to add a provider.
anthropic.nix- built-in Anthropic (envANTHROPIC_API_KEY), models: claude-opus-4-7 ("gawwd"), claude-sonnet-4-6 ("worker"), claude-haiku-4-5 ("haiya")office.nix- shared Juspay LLM provider (litellm,@ai-sdk/openai-compatible), used by both opencode and pi. Default modellitellm/open-large, explore agent usesopen-fast. 13 models: open-large/fast/vision, claude-opus/sonnet, glm, gemini, minimax, kimizen.nix- opencode Zen gateway (provider.opencode, built-in, envOPENCODE_API_KEY). Free models work without a key; with a key all 71 models loadopenrouter.nix- OpenRouter (provider.openrouter, built-in, envOPENROUTER_API_KEY)
combined-system-prompt.nix¶
A helper (not a module) - combines numbered markdown files in system-prompts/ (01-git, 02-before-you-code, 03-code-comments, 04-docs) into a single prompt string. Written to ~/.config/opencode/AGENTS.md by opencode/default.nix so it applies to every agent globally. Also used by claude.nix and pi.nix. Ponytail lives as a toggleable plugin, not a static prompt.
Usage:
browser¶
Auto-imported directory. Import via homeModules.browser. Web browser config - Zen (Firefox-based); containers keep Personal and Work logins from bleeding into each other.
zen/¶
Zen Browser (Firefox-based) via the zen-browser flake.
base.nix¶
- Containers: Personal (purple), Work (blue)
- 9 Zen mods (Quietify, PiP tweaks, Transparent Zen, Better CtrlTab, etc.)
- Session restore on startup, workspaces enabled, window sync
- Transparency enabled (for Transparent Zen mod)
- Policies: disable telemetry, studies, pocket, app update; tracking protection locked
- MIME associations: Zen as default for http/https/html/mailto/etc.
extensions.nix¶
Extensions via rycee/firefox-addons + AMO policies:
- rycee: ublock-origin, darkreader, simple-translate, firenvim, auto-tab-discard, duckduckgo, vimium, refined-github
- AMO: iCloud Passwords, Material Icons for GitHub, GitOwl, Nixpkgs PR Tracker, LanguageTool, Wide GitHub
keymaps.nix¶
Custom Zen keyboard shortcuts (compact mode, sidebar, workspaces, split views, pin, glance, copy URL).
search.nix¶
Custom search engines: DuckDuckGo default, hidden Google/Bing/Amazon/eBay. Added: Nix Packages (@np), Nix Options (@no), Home Manager (@hm), GitHub (@gh).
Usage:
terminal¶
Auto-imported directory. Import via homeModules.terminal.
kitty.nix¶
Kitty terminal with Monaspace fonts (with ligatures), transparency, cursor trail.
- Background opacity 0.85, blur 32, titlebar-only decorations
- Monaspace Radon Var font with all ligature features (dlig + ss01-ss08)
- Custom
tab_bar.py(frommisc/) - Cursor: beam with trail, blink
shift+entersends the kitty extended sequence- macOS:
cmd+optas alt, option-as-alt yes - MIME: vim-style keybindings (h/l seek, j/k cycle sub/audio)
- Stats overlay: JetBrainsMono, vim-style scroll
Usage:
hyprland¶
Auto-imported directory (modules/home/hyprland/). Import via homeModules.hyprland.
default.nix¶
- Auto-starts Hyprland via UWSM on TTY login (when no SSH + no tmux)
- Installs
grim,slurp,wl-clipboard - Aliases:
copy→wl-copy,paste→wl-paste
config.nix¶
Main Hyprland settings (Stylix-colored):
$mod = SUPER, dwindle layout, gaps 2/4, border 2- Input: US layout, follow mouse, touchpad natural scroll, repeat 50/300
- Group tabs with stylix colors, no gradients, 5px height
- Decoration: rounding 10, blur (size 6, passes 3, popups), no shadow
- Animations: custom bezier curves for windows/fade/workspaces
- Misc: swallow enabled, DPMS on mouse/key, session lock restore
keymaps.nix¶
Full keybind set (SUPER mod). Includes workspace navigation, window movement, focus (hjkl), resize, screenshots (grimblast), volume/brightness (utils), special workspaces (comms, quick), group submap, pass-through submap, rofi launcher.
Also sets up XDG user dirs (Screenshots) and installs grimblast, scratchpad, volume, brightness from hyprland-contrib + utils.
monitor.nix¶
Options for monitor setup:
| Option | Type | Default | Description |
|---|---|---|---|
ndots.hyprland.monitor.primary |
str | "DP-3" |
Primary monitor |
ndots.hyprland.monitor.secondary |
str | "DP-4" |
Secondary monitor |
Disables eDP-1, 10-bit color, secondary rotated (transform 3). Workspaces 1-9 on primary, 10 on secondary. IPC listener auto-runs monitor reconfigure on hotplug.
hypridle.nix¶
Idle daemon: lock at 290s, DPMS off at 300s, suspend at 360s.
hyprlock.nix¶
Screen lock with screenshot background (blurred), Road Rage font clock, stylix-colored input field.
rules.nix¶
Window/layer rules: float dialogs, comms apps to special workspace, blur on browsers/discord, idle inhibit for fullscreen video, quick-term dropdown styling.
rofi/¶
Rofi launcher (Wayland) with stylix-disabled theme, vim keys (Ctrl+hjkl). Keymaps bind Alt+Space leader for network/bluetooth/audio/emoji/power menus.
Usage:
{ flake, ... }: {
imports = [ flake.homeModules.hyprland ];
ndots.hyprland.monitor.primary = "DP-1";
}
darwin¶
Auto-imported directory (modules/home/darwin/). Import via homeModules.darwin.
aerospace/¶
AeroSpace tiling WM for macOS.
settings.nix¶
- Start at login, gaps 8, accordion padding 120
- Workspace-to-monitor assignments (1-5 primary, 6-9 secondary, 10 secondary)
- Floating apps: System Settings, Calculator, Finder, mpv, etc.
- Comms apps → Comms workspace (telegram, slack, discord, signal, etc.)
- After startup: borders + kitty dmenu panel
bindings.nix¶
Full keybinds with cmd-alt mod (capslock mapped to cmd-alt via Karabiner):
- hjkl focus (with mouse follow + wrap-around all monitors)
- shift+hjkl move, shift+space monitor swap, space monitor focus
- 1-0 workspaces, n/p next/prev, shift+1-0 move to workspace
- slash → fzf focus picker (via kitty panel)
- enter → kitty, m → fullscreen, f → float/tiling toggle
- Resize mode (hjkl), service mode (reload, flatten, enable toggle)
binding-script.nix¶
Floating window management via AppleScript:
movefloating- move floating window by offset (shift+arrows)resizefloating- resize floating window (ctrl+hjkl)centerfloating- center + 3/5 size floating window (ctrl+shift+c)
karabiner.nix¶
Installs the quick_hyper.karabiner.json complex modification (from misc/). Must be imported manually in Karabiner-Elements.
hammerspoon.nix¶
Hammerspoon automation. Installs the Hammerspoon app + a large init.lua:
- Hammerspoon Mode (
Ctrl+Opt+Shift+H): keyboard brightness control, reload, with visual indicator - SKHD Special Mode indicator: shows "SPECIAL" overlay when skhd special mode is active
- VimMode spoon: system-wide vim mode (enter with
jk), with extensive guards: - Disables in Code, MacVim, zoom, kitty, Maccy, Homerow, Minecraft
- Password field guard (disables in secure text fields)
- Firenvim guard (disables in browser-embedded Neovim)
- Hyper key guard (temporarily disables sequence during Hyper modifier)
- Spotlight + Emoji picker support
- Custom glass-style N/V mode indicator
jankyborders.nix¶
Focus borders for macOS.
- Style: round, width 1.0, HiDPI on
- Blacklist: ~25 system/utility apps (Finder, Messages, Calculator, etc.)
Usage:
{ flake, ... }: {
imports = [ flake.homeModules.darwin ];
# aerospace + karabiner + hammerspoon + jankyborders
}
stylix¶
Import via homeModules.stylix.
default.nix¶
Wires the stylix home-manager module + config + cli-only mode.
config.nix¶
The shared theme config (used by NixOS, Darwin, and home-manager):
| Setting | Value |
|---|---|
base16Scheme |
kanagawa-dragon |
image |
gruvbox pixelart wallpaper |
opacity.terminal |
0.4 |
polarity |
dark |
fonts.monospace |
Monaspace Radon Var |
cli-only.nix¶
Adds a stylix.cliOnly option. When enabled, disables GUI targets that require dconf/GTK (for headless/CLI-only setups):
Usage:
{ flake, ... }: {
imports = [ flake.homeModules.stylix ];
stylix.cliOnly = true; # for servers / CLI-only users
}
packages.nix¶
GUI packages + nixcord. Not meant for external use - contains personal app preferences.
- Both platforms: google-chrome, telegram-desktop, tart, softnet
- Darwin: mas, bruno, ytmdesktop
- nixcord: Discord client with messageLogger, showMeYourName, fakeNitro plugins, vencord enabled
syncthing.nix¶
Peer-to-peer file sync. Devices: mach, dsd, semi, jp-mbp. Folders: ~/.notes, ~/.dump.
Use absolute paths
Syncthing doesn't expand ~. Paths use config.home.homeDirectory.
folders."${config.home.homeDirectory}/.notes" = {
id = "notes";
devices = [ "mach" "dsd" "semi" "jp-mbp" ];
};
sops.nix¶
Home-level sops. Age key at ~/.config/sops/age/keys.txt, default file secrets/keys.yaml. Sets SOPS_AGE_KEY_FILE env var.
ssh.nix¶
SSH client config.
forwardAgent = true,addKeysToAgent = "yes"sendEnv:JUSPAY_*,GITHUB_*,ANTHROPIC_*,CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS- Darwin:
useKeychain = true - Forces
.ssh/config(avoids home-manager collision) - Linux:
ssh-agentservice enabled
mpv.nix¶
Media player with modernx-zydezu OSC.
- Fonts symlinked for macOS (modernx icons)
- Vim keybindings: h/l seek, j/k cycle subs/audio
- Stats overlay: JetBrainsMono, vim-style
- MIME: default for all video types
save-position-on-quit,ytdl-format = bestvideo+bestaudio
zathura.nix¶
PDF/document viewer (mupdf + djvu + ps backends).
- Vim keybindings (u/d scroll, J/K zoom, R reload, r rotate, i recolor)
selection-clipboard clipboard, sqlite database, minimal UI- MIME: default for PDF and PowerPoint
aria2.nix¶
aria2 download manager with optimized settings:
file-allocation = "falloc";
max-concurrent-downloads = 20;
max-connection-per-server = 10;
split = 4;
min-split-size = "10M";
nix-index.nix¶
nix-index + nix-index-database.
,(comma) command to run programs not in PATHCOMMA_PICKER = fzf(fzf picker for ambiguous commands)- Zsh integration enabled
nix-conf-fix.nix¶
Activation hook that fixes attic-client's bare substituters/trusted-public-keys in ~/.config/nix/nix.conf by converting them to extra- prefixed equivalents (needed for multi-user Nix where user-level bare settings are ignored).
home-only.nix¶
For standalone home-manager (not NixOS/Darwin). Adds homeModules.default + flakeModules.nix (nix settings).
naste.nix¶
naste CLI client with endpoint pre-configured. Imported by homeModules.default (all users). Hosts with sops add private.userFile/passFile in their user config.
{ flake, ... }: {
imports = [ flake.inputs.naste.homeModules.default ];
programs.naste-client = {
enable = true;
endpoint = "https://paste.semi.sh";
};
}
See naste service docs for private credential setup per host.