How ppcamp/dotfiles works
1. Repo purpose and runtime
This is a ChezMoi-managed dotfiles repository, not an application. The main “runtime” is ChezMoi itself: it renders templates, materializes files into the user’s home directory, and triggers scripts when tracked inputs change.
2. Primary orchestration layer
The root ChezMoi files define how the repo is applied:
- .chezmoi.yaml.tmpl, .chezmoidata.yaml, .chezmoiignore
- .chezmoiscripts/ for lifecycle hooks
- .chezmoitemplates/ for shared template fragments
These form the control plane that decides what gets installed, when, and with which host-specific values.
3. Declarative vs imperative boundary
The repo has a clear split between:
- declarative managed dotfiles and templates
- imperative run_onchange_* scripts that perform installation/setup work
That boundary is important: ChezMoi manages file state, while scripts handle provisioning, package installs, and system setup.
4. Package/tool bootstrap subsystem
The large set of .chezmoiscripts/run_onchange_install-*.tmpl files is the provisioning engine for local tooling. It covers package managers and utilities such as:
- asdf, homebrew, brew-like tooling
- CLI tools (fzf, rg, yq, zoxide, lazygit, gh, bat, eza, podman, nvim, etc.)
- optional sudo-backed installs for system-wide tools
This suggests a “tooling platform” architecture rather than a single-language project.
5. Shell environment subsystem
dot_local/share/shell/ is a self-contained Zsh environment with:
- internal config loading
- plugins
- snippets
- completion definitions
It is paired with shell entry files such as dot_zshenv.tmpl and dot_local/share/shell/init.zsh.tmpl. The shell layer is the user’s command-line base, with plugin-style composition for aliases, completions, SSH agent handling, fzf, zoxide, tldr, and prompt/utility behavior.
6. Editor/IDE subsystem: Neovim
dot_config/nvim/ is a full Neovim distribution layered on LazyVim-style plugin management. It includes:
- core config and keymaps in lua/config/
- custom commands in lua/commands/
- reusable utilities in lua/utils/
- plugin modules in lua/plugins/
- LSP server configs in lsp/
This is a major subsystem with its own internal architecture, distinct from the shell config.
7. Neovim integration boundaries
The Neovim config is split by capability:
- editor behavior, UI, and startup
- language tooling via LSP, completion, formatting, linting, debugging
- UI plugins for buffers, statusline, notifications, file explorer, start page, etc.
- AI-assisted editing via lua/plugins/ai.lua
This makes Neovim both an editor and an IDE shell around external language servers and developer tools.
8. AI assistant / agent tooling
dot_claude/ and dot_openclaude/ define local AI assistant workflows:
- agent definitions
- commands
- skills
- memory/state directories
- settings files
This is a separate operational boundary from the editor and shell: it provides prompt/agent behavior, workflows like review/help/refactor, and local persistent context.
9. Host and platform-specific integrations
Several files target OS/runtime integration rather than general config:
- dot_config/distrobox-home/ and tools/Containerfile for containerized Linux user environments
- dot_ssh/allowed_signers.tmpl for SSH trust configuration
- dot_git-template, dot_gitconfig.tmpl, dot_golangci.yml, dot_lefthook.yaml
- dot_config/kitty/, dot_config/lazygit/, dot_config/starship.toml
These are the “adjacent systems” around the shell/editor core.
10. Provisioning helpers and custom scripts
The tools/ directory contains standalone utility scripts (gitx, now, perm, screenreader, xcp, xpb) plus a container profile JSON. These are likely installed or symlinked into the user’s PATH and complement the shell plugins and completions.
11. Shared assets and generated files
dot_local/share/fonts/ and shell completion files under dot_local/share/shell/completions/ are asset-like managed content. They are not logic-heavy, but they matter in the architecture because they are the distribution mechanism for CLI ergonomics and terminal/UI consistency.
12. Documentation as part of the configuration system
docs/ is substantial and documents operational choices for ASDF, Kitty, Neovim, Git, GRUB, zsh, package inspection, and program recommendations. In practice, this repo is a documented operating environment, not just a file dump.
13. Overall data flow
The main flow is: repository state + host data + templates → ChezMoi renders files → files land in home/config paths → shell/editor/assistant tooling consumes them → run_onchange scripts provision missing packages or system setup when inputs change. That is the key architecture diagram to draw.
Main entry points: .chezmoi.yaml.tmpl ChezMoi root · configs.zsh Shell core · run_onchange_install-asdf.tmpl Tool installers · .chezmoiscripts Lifecycle scripts
Components 23
Control plane
ChezMoi entrypoints, shared templates, and lifecycle hooks.
- ChezMoi root · Top-level templates and managed-state rules that drive the repo.
.chezmoi.yaml.tmpl - Host data · Host- and machine-specific values used during rendering.
.chezmoidata.yaml - Ignore rules · Files excluded from management or rendering.
.chezmoiignore - Shared templates · Reusable template fragments for installs and common logic.
.chezmoitemplates
Bootstrap
Imperative provisioning and install scripts driven by ChezMoi.
- Lifecycle scripts · Imperative hooks that provision tools and react to changes.
.chezmoiscripts - Tool installers · Install and setup scripts for CLI tools, system packages, and optional sudo-backed installs.
.chezmoiscripts/run_onchange_install-asdf.tmpl
Shell
Zsh environment, plugins, snippets, and completions.
- Shell entry · Entry files that assemble the interactive shell environment.
dot_zshenv.tmpl - Shell core · Shared configs, loaders, paths, variables, and plugin wiring.
dot_local/share/shell/internal/configs/configs.zsh - Shell plugins · Composable shell features such as aliases, env cache, fzf, gh, pet, ssh-agent, tldr, and zoxide.
dot_local/share/shell/plugins - Shell snippets · Small reusable shell functions and aliases.
dot_local/share/shell/snippets - Completions · Generated and managed command completion definitions.
dot_local/share/shell/completions
Neovim
Full editor/IDE configuration and language tooling.
- Neovim entry · Main Neovim entrypoint and startup wiring.
dot_config/nvim/init.lua - Core config · Options, keymaps, lazy loader state, and core behavior.
dot_config/nvim/lua/config - Plugin stack · Editor, IDE, UI, AI, and workflow plugin modules.
dot_config/nvim/lua/plugins - LSP configs · Per-server configuration for language tooling integration.
dot_config/nvim/lsp
AI assistants
Local assistant workflows, agents, skills, and memory.
- Claude setup · Claude-related settings, commands, agents, skills, and memory.
dot_claude - OpenClaude · Alternative assistant workflows, agents, rules, and skills.
dot_openclaude
System integrations
Host, terminal, and platform-specific configuration.
- Kitty config · Terminal emulator settings and helper scripts.
dot_config/kitty - Prompt · Cross-shell prompt configuration.
dot_config/starship.toml - Git setup · Git defaults, templates, hooks, and trust-related settings.
dot_gitconfig.tmpl
Tools
Standalone helper scripts and container assets.
- Tool scripts · Standalone helper commands exposed through the user PATH.
tools/scripts - Container tools · Containerfile and profile assets for isolated Linux environments.
tools/Containerfile
Docs
Repository documentation and operational guidance.
- Docs · Operational guidance and setup notes for the environment.
docs
Connections 27
- ChezMoi root → Host data: uses · Rendering combines repo defaults with host data.
- ChezMoi root → Ignore rules: filters · Exclude paths from management.
- ChezMoi root → Shared templates: renders with · Templates provide shared logic for managed files and scripts.
- ChezMoi root → Lifecycle scripts: drives · ChezMoi lifecycle hooks coordinate provisioning.
- Lifecycle scripts → Tool installers: installs · Install hooks provision packages and tools.
- Lifecycle scripts → Container tools: sets up · Some hooks build container-based environments.
- ChezMoi root → Shell entry: materializes · Managed shell entry files land in the home directory.
- Shell entry → Shell core: loads · Entry scripts source core shell configuration.
- Shell core → Shell plugins: composes · Core shell behavior is extended by plugins.
- Shell core → Shell snippets: sources · Reusable snippets extend interactive shell behavior.
- Shell core → Completions: enables · Completion definitions are wired into the shell.
- ChezMoi root → Neovim entry: materializes · Neovim distribution is installed as managed config.
- Neovim entry → Core config: boots · Startup loads core options, keymaps, and state.
- Neovim entry → Plugin stack: loads · Plugin modules define the editor and IDE stack.
- Plugin stack → LSP configs: integrates · Plugins connect Neovim to language servers.
- ChezMoi root → Claude setup: materializes · Claude assistant configuration is managed by ChezMoi.
- ChezMoi root → OpenClaude: materializes · OpenClaude workflows are managed separately from editor config.
- ChezMoi root → Kitty config: materializes · Terminal configuration is deployed as user config.
- ChezMoi root → Prompt: materializes · Prompt configuration is rendered into the environment.
- ChezMoi root → Git setup: materializes · Git configuration and templates are managed files.
- ChezMoi root → Tool scripts: deploys · Helper commands are made available in PATH.
- ChezMoi root → Docs: documents · Docs describe the operating environment and setup choices.
- Tool installers → Shell plugins: supports · Installed tools back shell plugins and completions.
- Tool installers → Plugin stack: supports · Tooling installs satisfy editor plugins and IDE features.
- Tool installers → Claude setup: supports · AI assistant workflows depend on local tools and models.
- Tool scripts → Shell core: used by · Utilities are exposed through shell functions and shortcuts.
- Container tools → Shell entry: isolates · Container environments reuse the shell configuration.