modules.md

Modules

The shared base is Zsh, Bash, Git, tmux, and useful aliases on Linux and macOS. Original command names stay intact except rm, which uses recoverable trash. The base also installs add_iso_prefixes.sh and open_github.sh in ~/.local/bin. Standalone app configs are also always managed: Ghostty (~/.config/ghostty), Kitty (~/.config/kitty), LunarVim (~/.config/lvim), VS Code (~/.config/Code), Zed (~/.config/zed), marimo (~/.config/marimo), Tridactyl (~/.config/tridactyl), NetHack (~/.nethackrc) and Nix (~/.config/nix). Claude settings (~/.claude), Codex preferences (~/.codex) are always managed too. Applying configs does not install the applications. System settings, toolchain installation and dictation remain opt-in.

Zed's settings modifier merges shared defaults into the existing JSONC settings, or an empty object on a fresh install. Shared values take precedence; unrelated local keys, including nested settings, remain local. This preserves SSH connections, agent-server definitions and model choices. Output is formatted JSON, so comments and original formatting are not preserved. The shared defaults set editor behavior and appearance, including the tracked Nori Green theme. Zed and its configured fonts must be installed separately; the Linux fonts module is optional.

Only the explicitly tracked AI-tool files are managed. Credentials, sessions and Nori CLI project trust/first-launch state remain local. Nori CLI preferences are deferred until the pre-rewrite config is copied from the other laptop; it was never tracked in this repository. Pi configuration is deferred.

Claude settings render the skills directory and Handroll hook commands from chezmoi's home directory, so the source is portable across Linux and macOS. Hook commands retain Handroll's bin/../scripts path spelling to match the installer-generated commands. Handroll must be installed separately. Keep object keys alphabetically ordered at every level with two-space indentation to match Handroll's formatting; preserve array order. Applying replaces ~/.claude/settings.json; it does not merge local hooks or other local settings into the managed file.

Warp, Alacritty, k9s, Poetry, Gemini and OpenCode configs have been retired. Apply removes only their previously managed config files, preserving other application files and installed packages. The old configs remain available in Git history.

Tmux loads Catppuccin when installed. The contribution graph builds when Cargo is available and displays in interactive Zsh login shells when its binary exists.

Catalog

Module	Opinion / purpose	Platform
keyboard-remapping	Physical-key remapping; macOS implementation TODO	Linux; macOS planned
fonts	IBM Plex Sans, Noto fallback, FiraCode Nerd Font Mono	Linux with apt
desktop-apps	Firefox, VLC, Zed and Ghostty defaults when installed	Linux
de-cosmic	Native RON settings: compact dark desktop, panel, vertical workspaces	Linux / COSMIC
de-macos	macOS app-menu shortcuts, text-navigation bindings and AeroSpace config	macOS
boot-theme	Coffee splash, lock-cat disk prompt; key login artwork staged only	Pop!OS 24.04
dev-tools	Pinned mise tools, automatic installation and shell integration	Linux / macOS
memory-protection	Per-machine tmux scope memory limits and user-manager OOM policy	Linux / systemd
llama-cpp	Local inference runtime, browser chat UI and OpenAI-compatible API	Linux x86_64 / systemd
dictation	On-device streaming speech to clipboard; optional desktop shortcut	Linux / systemd

Platform labels describe intended scope, not cross-platform validation.

Composition and ownership

data.modules in ~/.config/chezmoi/chezmoi.toml selects modules; none are enabled by default. The catalog maps names to managed paths; ignore rules enforce selection and platform boundaries. Remove old standalone-app and retired-app names from data.modules when updating; those entries no longer control any paths. Rename cosmic to de-cosmic and builtin-keyboard to keyboard-remapping. On macOS, select de-macos for the shortcut setup and AeroSpace config; it replaces the old mac-shortcuts entry, whose script ran without checking selection.

Chezmoi uses an explicit 0022 umask: ordinary files are 0644, executable files and directories 0755; private_ attributes remove group/other access.

• fonts needs de-cosmic for COSMIC font preferences; Fontconfig settings stand alone.
• de-cosmic requires ImageMagick for hostname-colored wallpaper generation; install it manually before applying.
• memory-protection requires data.tmuxMemory.high, .max, and .swap; it limits matching tmux scopes, not their creation, and sets DefaultOOMPolicy=continue for the user manager.
• llama-cpp installs a pinned Vulkan runtime and an opt-in user service; provide a GGUF model separately. Its service and memory-protection own separate systemd paths and can be selected independently.
• Most modules configure existing tools. fonts, dev-tools and dictation install their runtimes or dependencies; Linux keyboard-remapping and boot-theme install system configuration through sudo.
• Disabling a module stops management. It does not remove applied files, packages, or system changes.

Selection: chezmoi edit-config. Review: chezmoi diff. Apply: chezmoi apply.

memory-protection replaces tmux-memory and user-oom-policy. Replace either old name in data.modules with memory-protection; both policies are now managed together. Existing [data.tmuxMemory] values and deployed file paths stay the same. If only user-oom-policy was selected, also set the three per-machine memory limits before applying. Machines with neither selected remain opt-out.

When enabling it through chezmoi edit-config, add the limits too; editing the module list does not run the chezmoi init prompts. For example:

[data.tmuxMemory]
high = "24G"
max = "32G"
swap = "8G"

These are the setup's suggested values; choose limits appropriate to the machine. Missing limits cause chezmoi status, diff and apply to fail until configured.