Imported from darkiop/dotfiles (AGENTS.md). Install upstream with npx skills add darkiop/dotfiles. Copyright stays with the author.

Keep in sync: AGENTS.md, CLAUDE.md, .github/copilot-instructions.md

Overview

Personal bash/zsh dotfiles with modular components and submodules. Goals: minimal changes, POSIX-friendly, preserve per-host feature flags.

Repository Structure

dotfiles/
├── alias/              # Shell aliases (9 files by category)
│   ├── alias           # Main aliases (sudo prefixes, global)
│   ├── alias-docker    # Docker commands
│   ├── alias-git       # Git commands
│   ├── alias-systemctl # Systemctl commands
│   ├── alias-proxmox   # Proxmox VE commands
│   ├── alias-wireguard # WireGuard VPN
│   ├── alias-glusterfs # Gluster filesystem
│   ├── alias-iobroker  # ioBroker smart home
│   └── alias-navi      # Navi cheat widget
├── bash_completion.d/  # Custom bash completions
├── bin/                # Helper scripts
├── cheats/             # Navi cheat files (.cheat format)
├── components/         # 27 modular shell components
├── config/             # Configuration files
│   ├── dotfiles.config       # Colors and global settings
│   ├── catppuccin.sh         # Catppuccin palette (CAT_*, raw escapes)
│   ├── local_dotfiles_settings # Per-host overrides (gitignored)
│   ├── dot_help.json         # Database for `dot help`
│   ├── tmux.conf.local       # Tmux local overrides
│   └── helix/                # Helix editor config
├── modules/            # Git submodules (shallow)
│   ├── fzf/            # Fuzzy finder
│   ├── fzf-tab-completion/ # Tab completion with FZF preview
│   ├── oh-my-zsh/      # Zsh framework (optional)
│   ├── oh-my-tmux/     # Tmux configuration framework
│   ├── tpm/            # Tmux Plugin Manager
│   └── vimrc/          # Vim configuration
└── motd/               # Message of the day system
    ├── motd.sh         # Main MOTD renderer
    ├── motd-catppuccin-mocha.sh # Themed entry point (login + `motd` alias)
    ├── widgets.sh      # Widget system with caching
    ├── palette.sh      # MOTD status colours (maps config/catppuccin.sh)
    ├── widgets/        # Custom widget extensions
    └── systemd/        # Timers for background updates

Components

Category	Components
Shell	`bash_prompt_catppuccin_mocha`, `zsh_prompt`, `bash_defaults`, `zsh_defaults`, `bash_completion`, `zsh_completion`
FZF	`fzf` (loader), `fzf_core`, `fzf_tab_completion`, `fzf_git`, `fzf_tmux`, `fzf_docker`, `fzf_systemctl`, `fzf_extras`
Pickers	`ssh_picker`, `journalctl_picker`, `log_picker`
Tools	`dot_help`, `dot_doctor`, `dot_profile`, `helpers`, `navi`
System	`platform`, `path`, `feature_flags`, `brew`, `lazy_loader`

Shell Loading Order

bashrc/zshrc
├── config/dotfiles.config (colors, settings)
├── components/path ($PATH from DOTFILES_PATH_FRONT/BACK)
├── components/platform (OS detection)
├── components/feature_flags (load flags + local overrides)
├── components/*_defaults (shell settings)
├── components/*_prompt (if enabled)
├── components/fzf (if enabled: sources fzf_core, plus
│      fzf_tab_completion when DOTFILES_ENABLE_FZF_TAB_COMPLETION)
├── components/fzf_git, fzf_extras, fzf_tmux (if enabled)
├── components/lazy_loader (if enabled: registers stubs for
│      ssh_picker, journalctl_picker, log_picker, … instead of
│      sourcing them; the real component loads on first call)
├── alias/* (if enabled)
├── components/helpers (if enabled)
└── components/navi (if enabled)

Key Commands

Command	Description
`dot help`	Command and keybinding overview
`dot doctor`	Diagnose common problems
`dot alias`	Show aliases with availability status
`dot update`	Update dotfiles and reload shell
`dot profile`	Measure shell startup time per component
`fh`	FZF history picker
`cdf`	FZF directory picker
`gco`	Git checkout (branch picker)
`gshow`	Git show (commit picker)
`ts`/`tw`/`tp`	Tmux session/window/pane picker
`sshp`	SSH host picker
`dcheat`/`cheat`	Local cheat sheet navigation

MOTD Widgets

Built-in widgets in motd/widgets.sh:

docker — running/stopped container counts
tailscale — Tailscale IP or status
wireguard — WireGuard IP and allowed IPs
proxmox — LXC/VM counts (running/total)
homebrew — available updates (formulas/casks)
network — host reachability status

Entry Points

Install: install.sh (or curl one-liner in README.md)
Update: dot update or manually: git pull --ff-only && git submodule update --init --recursive --depth 1
Auto-update: autoupdate.sh via DOTFILES_ENABLE_AUTOUPDATE

Key Files

Purpose	Files
Config & flags	`components/feature_flags`, `components/platform`, `components/path`, `config/local_dotfiles_settings`
Shell entry	`bashrc`, `zshrc`, `bash_profile`, `zprofile`
Prompts	`components/bash_prompt_catppuccin_mocha`, `components/zsh_prompt`
FZF	`components/fzf` (loader), `components/fzf_core`, `components/fzf_tab_completion`, `components/fzf_docker`, `components/fzf_git`, `components/fzf_systemctl`, `components/fzf_tmux`, `components/fzf_extras`
Utilities	`components/dot_doctor`, `components/dot_help`, `components/dot_profile`, `components/helpers`, `components/lazy_loader`
Pickers	`components/ssh_picker`, `components/journalctl_picker`, `components/log_picker`
Tmux	`modules/oh-my-tmux/.tmux.conf.local`, `config/tmux.conf.local`
MOTD	`motd/motd.sh`, `motd/motd-catppuccin-mocha.sh`, `motd/widgets.sh`, `motd/palette.sh`, `motd/widgets/<short-hostname>/`
Help data	`config/dot_help.json`

Conventions

Feature flags: Add to components/feature_flags, override in config/local_dotfiles_settings
Submodules: Installed via git clone --recurse-submodules; gitconfig sets submodule.recurse=true
Tool installation: Via module scripts (e.g., modules/fzf/install), not distro packages
Platform detection: Use DOTFILES_OS, DOTFILES_DISTRO_ID, DOTFILES_WSL, DOTFILES_WSL_VERSION, DOTFILES_CONTAINER from components/platform
Line endings: LF only (see .gitattributes)
Component naming: FZF components use fzf_ prefix, pickers use _picker suffix

Testing

Syntax check: bash -n path/to/file
Manual test: source bashrc or open new shell

Editing Guidelines

Make small, focused edits preserving existing style
Put user-facing defaults behind feature flags
New modules need install script and README.md under modules/<name>/
Use components/platform for OS checks, not hardcoded conditions
Keep install.sh idempotent (skip if already installed)
Keep README.md in sync: Update relevant sections when changing features, commands, bindings, or flags

Implementation Examples

Task	How
New prompt segment	Edit `components/bash_prompt_catppuccin_mocha` and `components/zsh_prompt`, update README
New alias set	Create `alias/alias-<name>`, source from `alias/alias`
New completion	Add to `bash_completion.d/`, enable via `DOTFILES_ENABLE_BASH_COMPLETION`
New FZF integration	Create `components/fzf_<name>`, add `DOTFILES_ENABLE_<NAME>_FZF` flag
New picker	Create `components/<name>_picker`, add flag, follow `ssh_picker` template
New MOTD widget	Create script in `motd/widgets/`, register in `motd/widgets.sh`

Feature Flags

All default to true unless noted. Override in config/local_dotfiles_settings.

Flag	Description
`DOTFILES_ENABLE_PROMPT`	Custom bash/zsh prompt
`DOTFILES_ENABLE_BASH_COMPLETION`	Bash completions
`DOTFILES_ENABLE_FZF`	FZF integration
`DOTFILES_ENABLE_NAVI`	Navi cheatsheet tool
`DOTFILES_ENABLE_ALIASES`	Load alias files
`DOTFILES_ENABLE_SSH_PICKER`	SSH host picker (Ctrl+S)
`DOTFILES_ENABLE_GIT_FZF`	Git FZF integration
`DOTFILES_ENABLE_FZF_EXTRAS`	Additional FZF functions
`DOTFILES_ENABLE_FZF_HISTORY_BINDINGS`	FZF history search
`DOTFILES_ENABLE_FZF_CDF_BINDING`	cd with FZF (Alt+C)
`DOTFILES_ENABLE_HELPERS`	Helper functions
`DOTFILES_ENABLE_FZF_TAB_COMPLETION`	FZF-based tab completion
`DOTFILES_ENABLE_EXTRACT_EXT`	Archive extraction helper
`DOTFILES_ENABLE_BREW`	Homebrew integration
`DOTFILES_ENABLE_OH_MY_ZSH`	Oh My Zsh (default: false)
`DOTFILES_ENABLE_MOTD`	Message of the day (default: false)
`DOTFILES_ENABLE_MOTD_AUTO_RUN`	Auto-show MOTD on login (default: false)
`DOTFILES_ENABLE_MOTD_WIDGETS`	MOTD widget system
`DOTFILES_ENABLE_NETWORK_WIDGET`	MOTD network reachability widget (default: false)
`DOTFILES_MOTD_STYLE`	MOTD layout: `tree` (default) or `default`
`DOTFILES_ENABLE_LAZY_LOADING`	Lazy-load rarely used components
`DOTFILES_ENABLE_LOG_PICKER`	macOS log picker (default: macOS only)
`DOTFILES_ENABLE_AUTOUPDATE`	Auto-update dotfiles
`DOTFILES_ENABLE_TMUX_AUTOSTART`	Auto-start tmux
`DOTFILES_ENABLE_SSH_TMUX_RENAME`	Rename tmux window on SSH
`DOTFILES_ENABLE_TMUX_FZF`	Tmux FZF integration
`DOTFILES_ENABLE_JOURNALCTL_PICKER`	Journalctl unit picker
`DOTFILES_ENABLE_SYSTEMCTL_FZF`	Systemctl FZF integration
`DOTFILES_ENABLE_DOT_DOCTOR`	Diagnostics command
`DOTFILES_ENABLE_DOCKER_FZF`	Docker FZF integration
`DOTFILES_ENABLE_DOT_HELP`	Help system
`DOTFILES_ENABLE_DOT_HELP_BINDING`	Help keybinding (F1)
`DOTFILES_ENABLE_RELOAD_BINDING`	Reload shell binding
`DOTFILES_ENABLE_IOBROKER`	ioBroker integrations

Change Checklist

Before committing user-facing changes:

Code changes implemented and tested
Feature flags added/updated in components/feature_flags
config/dot_help.json updated (if adding commands/bindings)
README.md sections updated (features, flags, bindings, etc.)
CLAUDE.md updated if new conventions established

dotfiles

About