Home Manager Modules
User-level configuration: programs, dotfiles, theming, desktop environment.
Most modules directly configure programs.*, services.*, home.*; ai-agents/ is the exception and defines programs.aiAgents.* options.
Module Hierarchy
modules/
├── ai-agents/ # AI coding agent config (Claude Code, OpenCode, Codex, Gemini CLI)
│ ├── default.nix # Import hub (options, activation, files, services, config)
│ ├── options.nix # All programs.aiAgents option definitions
│ ├── files.nix # home.file + xdg.configFile declarations
│ ├── packages.nix # Packages, zsh aliases, systemd user services/timers, log analysis
│ ├── helpers/ # Shared logic (not modules, imported by others)
│ │ ├── _settings-builders.nix # Per-agent settings + profile variant overrides
│ │ ├── _mcp-transforms.nix # Unified MCP abstraction (shared → agent-specific)
│ │ ├── _opencode-profiles.nix # OpenCode profile names and config paths
│ │ ├── _aliases.nix # Zsh alias generation for agent launchers/workflows
│ │ ├── _destructive-rules.nix # Destructive action allow/deny rules per agent
│ │ ├── _file-templates.nix # Config file templates
│ │ ├── _gemini-policies.nix # Gemini CLI safety policy definitions
│ │ ├── _workflow-prompts.nix # Workflow prompt definitions
│ │ ├── _zai-services.nix # Z.AI MCP service registry
│ │ ├── _zai-filters.nix # Z.AI MCP jq filter generation
│ │ ├── _zai-config.nix # Z.AI API root, timeout, model identifiers
│ │ ├── _mk-cli-autoupdate-script.nix # CLI autoupdate script builder
│ │ ├── _services-shell-aliases.nix # Shell alias definitions for agent services
│ │ ├── _services-systemd.nix # Systemd user service/timer definitions
│ │ ├── _formatters.nix # Formatter registry for auto-formatting hooks
│ │ ├── _impeccable-commands.nix # Impeccable slash command definitions
│ │ ├── _models.nix # Shared model/provider constants (names, aliases)
│ │ ├── _opencode-gruvbox-theme.nix # OpenCode Gruvbox Dark TUI theme
│ │ ├── _agent-env.nix # Agent environment variable bridging
│ │ ├── _zai-env.nix # Z.AI provider env vars (shared by claude_glm + Android RE launchers)
│ │ ├── _git-clone-update.nix # Git clone/update helper for plugin repos
│ │ └── workflows/ # Workflow prompt Nix expressions (9 files)
│ ├── activation/ # Home Manager activation scripts
│ │ ├── default.nix # Aggregation hub
│ │ ├── secrets.nix # Secret patching (placeholder → real key injection)
│ │ ├── claude-setup.nix # Claude Code config file writes
│ │ ├── codex-setup.nix # Codex CLI config file writes
│ │ ├── plugins.nix # Plugin aggregation (impeccable, agency-agents, ECC)
│ │ ├── _plugin-impeccable.nix # Impeccable skill install
│ │ ├── _plugin-agency-agents.nix # Agency agents install
│ │ ├── _plugin-everything-claude-code.nix # ECC skill install
│ │ ├── _cleanup-agency-agents.nix # Agency agents cleanup on disable
│ │ ├── _cleanup-everything-claude-code.nix # ECC cleanup on disable
│ │ ├── skills.nix # Skill installations and omissions
│ ├── android-re/ # Android RE workflow prompts and config
│ │ ├── _launchers.nix # Android RE emulator/script launchers (not a module, imported by packages)
│ │ ├── _prompt.nix # Prompt templates (not a module, imported by services)
│ │ └── prompts/ # RE prompt docs (AGENTS.md, README, TOOLS, WORKFLOW, TROUBLESHOOTING)
│ ├── web-re/ # Web RE workflow prompts and config
│ │ ├── _launchers.nix # Web RE launchers (not a module, imported by packages)
│ │ ├── _prompt.nix # Prompt templates (not a module, imported by services)
│ │ └── prompts/ # RE prompt docs (AGENTS.md, README, TOOLS, WORKFLOW, TROUBLESHOOTING)
│ └── config/ # Split configuration values
│ ├── default.nix # Import hub (defaults, mcp-servers, models, claude)
│ ├── defaults.nix # Default values for agent options
│ ├── global-instructions.md # Global instructions text (not a module)
│ ├── _skills.nix # Skill installations and omissions (not a module)
│ ├── mcp-servers.nix # MCP server definitions + logging
│ ├── mcp-servers-android-re.nix # Android RE MCP server definitions
│ ├── mcp-servers-web-re.nix # Web RE MCP server definitions
│ ├── claude/ # Claude Code configuration
│ │ ├── default.nix # Permissions, hooks, settings (import hub)
│ │ ├── _hooks.nix # Lifecycle hooks aggregation (imports helpers + per-stage modules)
│ │ ├── _hooks-helpers.nix # Shared hook constructors (mkFormatterHook, mkBashHook, etc.)
│ │ ├── _hooks-pre-tool-use.nix # Pre-tool-use safety hooks
│ │ ├── _hooks-post-tool-use.nix # Post-tool-use auto-format hooks
│ │ ├── _hooks-session.nix # Session lifecycle hooks
│ │ └── _permission-rules.nix # Claude allow/deny rules (not a module)
│ └── models/ # Model/provider registries
│ ├── default.nix # Import hub + shared toggles (agencyAgents, impeccable)
│ ├── codex.nix # Codex CLI config (model, profiles, custom agents, developer instructions)
│ ├── gemini.nix # Gemini CLI config (settings, theming, model aliases, auto-format hooks)
│ ├── opencode.nix # OpenCode config (agents, LSP, providers)
│ ├── _opencode-agents.nix # OpenCode agent definitions
│ ├── _opencode-commands.nix # OpenCode slash command definitions
│ ├── _opencode-android-re.nix # OpenCode Android RE agent definition
│ ├── _opencode-web-re.nix # OpenCode Web RE agent definition
│ ├── _opencode-lsp.nix # OpenCode LSP tool configuration
│ └── omp.nix # OMP CLI configuration
├── apps/ # App configs (OBS, Syncthing, KeePassXC, Discord, ActivityWatch, browsers, desktop entries)
│ ├── activitywatch.nix # ActivityWatch app usage tracking (Wayland)
│ ├── chromium.nix # Chromium launch wrapper with Wayland crash workaround
│ ├── desktop-entries.nix # Desktop launchers/wrappers
│ ├── keepassxc.nix # KeePassXC desktop entry
│ ├── nautilus.nix # Nautilus (GNOME Files) dconf preferences
│ ├── nixcord.nix # Discord (Vesktop + Vencord) declarative config
│ ├── obs.nix # OBS Studio with CUDA and plugins
│ ├── obsidian.nix # Obsidian Markdown notes app defaults
│ ├── opensnitch-ui.nix # OpenSnitch application firewall GUI
│ ├── metadata-scrubber.nix # Automatic metadata scrubbing (mat2/exiftool)
│ ├── syncthing.nix # Syncthing local file sync
│ ├── _desktop-local-bin-wrappers.nix # Desktop local bin wrappers (helper, not in default.nix)
│ ├── _mk-wayland-browser-wrapper.nix # Shared Wayland browser wrapper (helper, not in default.nix)
│ ├── vscode/ # VS Code editor
│ │ ├── default.nix # Import hub (enable, package, mutableExtensionsDir)
│ │ ├── extensions.nix # Extensions (nixpkgs + marketplace)
│ │ ├── _settings.nix # Settings builder (not a module, imported by activation)
│ │ ├── _builtin-extensions.nix # Built-in extension list (helper)
│ │ ├── _marketplace-refs.nix # Marketplace extension references (helper)
│ │ └── activation.nix # Writes mutable settings.json
│ ├── brave/ # Brave browser
│ │ ├── default.nix # Import hub
│ │ └── extensions.nix # Declarative extension groups (privacy, dev tools, YouTube/social)
│ └── librewolf/ # LibreWolf browser (multi-profile SOCKS5 proxy)
│ ├── default.nix # Import hub: programs.librewolf with policies + profiles
│ ├── _profiles.nix # Profile definitions (not a module, imported by desktop-entries.nix)
│ └── _extensions.nix # Extension declarations (not a module, imported by default.nix)
├── niri/ # Niri compositor (scrollable tiling Wayland)
│ ├── default.nix # Import hub
│ ├── main.nix # Compositor settings (autostart, workspaces, environment, animations)
│ ├── binds.nix # Keybindings and custom scripts
│ ├── _workspace-names.nix # Workspace display names (not a module, imported by main/binds/rules)
│ ├── _noctalia.nix # Noctalia Shell IPC helper with auto-start + retry (not a module, imported by binds/idle)
│ ├── input.nix # Input devices (keyboard, mouse, touchpad, trackpoint)
│ ├── layout.nix # Layout settings (columns, gaps, focus ring, border)
│ ├── rules.nix # Window rules (opacity, rounding, floating, workspace assignments)
│ ├── idle.nix # Idle management (DPMS, lock)
│ ├── lock.nix # Screen locker
│ └── scripts/ # Extracted helper scripts
│ ├── color-picker.nix # Wayland color picker (grim + slurp + imagemagick)
│ ├── open-books.nix # Book launcher (find + wofi + zathura)
│ └── screenshot.nix # Screenshot annotator (grim + slurp + swappy)
├── noctalia/ # Noctalia Shell (bar, launcher, notifications, wallpaper, OSD, GruvboxAlt colorscheme)
│ ├── default.nix # Import hub, status-notifier-watcher (SNI protocol)
│ ├── activation.nix # Activation script (wallpaper deployment, plugin compilation)
│ ├── bar.nix # Bar widgets (left, center, right panels)
│ ├── settings.nix # Shell settings (theme, dock, wallpaper, OSD, control center, lock command, hooks)
│ ├── _colorscheme.nix # GruvboxAlt colorscheme generator (produces JSON at activation)
│ ├── _plugins.nix # Plugin registry and configuration
│ └── plugins/ # Noctalia shell plugins
│ ├── browser-launcher/ # Browser profile launcher (QML)
│ ├── keybind-cheatsheet/ # Keyboard shortcut overlay (QML)
│ ├── mawaqit/ # Prayer time widget (QML)
│ ├── model-usage/ # AI model usage tracker (QML)
├── neovim/ # Neovim editor with LSP, completion, and modern plugins
│ ├── default.nix # Plugin declarations, treesitter, Lua config loading
│ ├── lua/ # Lua configuration (options, keymaps, LSP, plugins)
│ └── plugins/ # Plugin-specific configs (wakatime)
├── programming-languages/ # Language tooling (Go, JS, Python, Mise)
│ ├── go/ # Go runtime, aliases, GOPATH/GOBIN/session settings
│ │ └── default.nix
│ ├── javascript/ # Node/Bun/Deno toolchain, JS/TS aliases, Playwright wrapper
│ │ ├── default.nix
│ │ └── _gitignores.nix # Git ignore patterns (helper)
│ ├── python/ # Python toolchain, uv/poetry aliases, REPL config
│ │ ├── default.nix
│ │ └── _gitignores.nix # Git ignore patterns (helper)
│ └── mise/ # Mise polyglot runtime manager
│ └── default.nix
├── terminal/ # Shell, terminal, and CLI tools
│ ├── ghostty.nix # Ghostty terminal emulator
│ ├── zellij/ # Terminal multiplexer (WASM plugins, 4 layouts)
│ │ ├── default.nix # Import hub
│ │ ├── config.nix # Keybinds, UI, behavior
│ │ ├── layouts.nix # Layouts (default, dev, ai, monitoring)
│ │ └── plugins.nix # WASM plugins (zjstatus, autolock, monocle, room, harpoon, forgot, multitask)
│ ├── direnv.nix # Per-directory environments
│ ├── scripts.nix # Custom utility script wrappers (currently `nvidia-fans`)
│ ├── shell.nix # Nix shell integration and dev tools
│ ├── zsh/ # Zsh + Oh My Zsh (Starship handles the prompt)
│ │ ├── default.nix # Main zsh config with setOptions, OMZ
│ │ ├── aliases.nix # Shell aliases
│ │ ├── config.nix # Zsh settings and initialization
│ │ ├── functions.nix # Custom zsh functions (nix helpers, agent wrappers, aip)
│ │ └── local-vars.nix # Local shell variables
│ └── tools/ # CLI tools (atuin, bat, btop, cava, carapace, eza, fzf, gh, git, lazygit, mpv, starship, yazi, zathura, zoxide — 15 entries)
│ └── git/ # Git (identity from constants, GPG signing, aliases, hooks)
│ ├── default.nix # Import hub
│ ├── config.nix # Git settings, aliases, includes
│ └── hooks.nix # Global hooks (secret scanning, conventional commits, GPG)
├── gpg.nix # GPG agent and keys
├── ssh.nix # SSH client hardening
├── mime.nix # Default app associations
├── qt.nix # Qt theming (Kvantum + Gruvbox)
├── telemetry.nix # Telemetry and tracking opt-out variables
└── stylix.nix # Theming engine (Gruvbox)
Package Chunks (../packages/)
Packages live separately from modules. Each chunk is a Home Manager module:
{ pkgs, ... }:
{
home.packages = [ ... ];
}
9 domain chunks + 5 custom chunks + 1 helper: applications, cli, development, lsp-servers, networking, niri, privacy, system-monitoring, utilities, plus custom/beads, custom/chrome-devtools, custom/cursor, custom/kiro, custom/prayer, and ../_helpers/_egl-wrap.nix (helper, imported manually).
When adding packages: pick the domain chunk, add to its list. Don't create new chunks unless new domain.
Theming (Stylix)
- Base16 scheme:
gruvbox-dark-soft - Fonts: JetBrains Mono (mono), Noto Sans (sans), Noto Serif (serif)
- Cursor: Bibata-Modern-Classic (24px)
- Icons: Gruvbox-Plus-Dark
- GTK extra CSS: flat style —
border-radius: 0; box-shadow: noneon*selector
Stylix-Exempt Modules
Stylix has autoEnable = false — individual targets must be explicitly opted in. Currently enabled: ghostty, gtk, neovim, zellij.
- Noctalia Shell manages its own theming (not in the Stylix target list).
When adding a new program: add it to the explicit target list in stylix.nix if theming is desired. Skip if the program handles its own styling.
Configuration Patterns
Program Config (most common)
programs.<tool> = {
enable = true;
settings = { ... };
};
Service Config
services.<service> = {
enable = true;
settings = { ... };
};
Home Files (dotfiles)
home.file.".config/app/config" = {
text = ''...''; # or source = ./path;
};
xdg.configFile."app/style.css".text = ''...'';
Adding a New Module
- Create
home-manager/modules/<name>.nix - Add import with comment to
home-manager/modules/default.nix - Use
programs.*orservices.*— do NOT define custom options - Run:
just modules && just pkgs && just lint && just format && just check && just home
For subdirectory modules (e.g., new tool in terminal/tools/):
- Create the
.nixfile in the subdirectory - Add import to that subdirectory's
default.nix - Same validation pipeline
Sub-directory AGENTS.md
More detailed module-level guidance exists at:
ai-agents/AGENTS.md— Multi-agent architecture, profile variants, activation, hooksneovim/AGENTS.md— Neovim module boundaries, Lua/plugin wiring patternsterminal/AGENTS.md— Shell, multiplexer, CLI tools, one-per-tool patternterminal/zsh/AGENTS.md— Zsh + OMZ, aliases, agent wrappers, privacy historyterminal/tools/AGENTS.md— CLI tools (atuin, bat, fzf, gh, git, lazygit, yazi, etc.)niri/AGENTS.md— Compositor keybindings, workspaces, window rulesnoctalia/AGENTS.md— Noctalia Shell bar, settings, Stylix-exempt themingapps/AGENTS.md— Application configs, subdirectory modules (VS Code, Brave)programming-languages/AGENTS.md— Language toolchains (Go, JS/TS, Python, Mise)
Read these when working in those areas.
Notes
home.nixreceives{ inputs, homeStateVersion, user, pkgsStable, constants, optionHelpers, secretLoader, hmSystemdHelpers, hostname }viaextraSpecialArgsfrom flakehostnameavailable for host-specific HM configconstantsavailable fromshared/constants.nix(terminal, editor, font, theme, keyboard, user identity)- Git identity (name, email, signingKey, githubEmail) lives in
constants.user.*— used byterminal/tools/git/config.nix - HM modules are usually direct
programs.*/services.*configs; onlyprograms.aiAgents.*defines custom HM options