How chipwolf/dotfiles works
1. This repo is a machine bootstrap system, not just a config dump.
The source of truth lives under home/ and is applied to a user’s home directory through chezmoi. The repo targets four environments: macOS, Linux, Windows, and GitHub Codespaces.
2. The main boundary is “source state” vs “rendered machine state.”
.chezmoiroot makes home/ the chezmoi source tree. Filenames use chezmoi conventions like dot_, private_, and executable_, so the repo encodes both path mapping and file permissions. Templates (.tmpl) and data files drive per-machine variation.
3. Bootstrap is split from configuration content.
install.sh and install.ps1 are the entrypoints users run on a fresh machine. They are release artifacts, not hand-edited docs. Their job is to install the minimal prerequisites, run chezmoi init --apply, and then execute platform-specific setup steps.
4. Package management is platform-dependent but centrally declared.
On macOS/Linux/Codespaces, the main package boundary is Homebrew via home/Brewfile. On Windows, the equivalent boundary is Chocolatey. This is the primary place where host software gets installed outside the chezmoi file sync.
5. Runtime/toolchain provisioning is a second layer after packages.
mise.toml and home/dot_config/mise/config.toml.tmpl define managed runtimes like Python, Node, Go, etc. The bootstrap flow installs these runtimes after the base package manager work, so developer tools are available consistently across hosts.
6. The repo’s “developer workstation” stack is centered on shell, terminal, editor, and multiplexer configs.
- zsh + Powerlevel10k for macOS/Linux/Codespaces
- Oh My Posh for Windows
- tmux on Unix-like hosts
- Ghostty on macOS and WezTerm on Windows
- Neovim/LazyVim across all environments
These are separate config subsystems, but they form the interactive runtime surface of the machine.
7. There are clear OS-specific configuration branches.
macOS includes Finicky, GnuPG, Cursor, and Homebrew-based shell integration. Windows includes PowerShell profile, PowerToys, WezTerm, Oh My Posh, and Windows-specific user settings. Linux is primarily represented through the shared shell/editor/toolchain layer and WSL on Windows.
8. Windows has an extra virtualization boundary through WSL.
The Windows bootstrap provisions Ubuntu under WSL using cloud-init style automation, then clones and applies the same dotfiles inside the Linux environment. That means Windows actually contains two managed environments: native Windows config and a nested Linux bootstrap.
9. Codespaces is treated as a special deployment target with an optimized artifact path.
The repo ships a prebuilt container overlay image (Dockerfile, GHCR publication) used when CODESPACES=1. In that mode, install.sh skips the full bootstrap and extracts the overlay layers that differ from the base devcontainer. This is a performance and reproducibility boundary specific to Codespaces.
10. The repo also manages AI/tooling configuration as a first-class subsystem.
home/dot_config/opencode/ contains OpenCode config, plugins, agents, commands, and skills. There is also home/dot_cursor/mcp.json.tmpl plus MCP server data in home/.chezmoidata/mcp-servers.yaml. This layer controls local AI agent behavior and model/tool access, with some entries gated by the private flag.
11. Secrets and identity are modeled separately from the rest of the config.
The repo is wired for Bitwarden CLI (bw) as the secret manager, but templates currently do not require an active session to apply. Git identity and signing live in home/dot_gitconfig, while GnuPG/YubiKey guidance is documented rather than embedded directly into the bootstrap path.
12. Post-apply hooks finish the environment after files and packages exist.
Scripts under home/.chezmoiscripts/ handle tasks like prewarming zsh plugin caches, syncing Neovim plugins, and updating shell or tmux symlinks. These are important because they represent “after the files are in place” orchestration, not static config.
13. Validation is split between source-level and container-level tests.
tests/source/ checks the chezmoi/Brewfile behavior, while tests/container/ validates the overlay/container path. This mirrors the repo’s two deployment modes: direct machine bootstrap and Codespaces/container bootstrap.
14. Release and provenance are part of the architecture.
GitHub Actions workflows build the container image, upload install scripts, run tests, and publish releases. The repo emphasizes SLSA provenance for install scripts and the Codespaces image, so the delivery pipeline is treated as part of the trusted system boundary.
15. In diagram terms, the key flow is: repo source → chezmoi rendering → platform bootstrap → package/runtime installation → post-install hooks → interactive workstation.
The important branching points are the host OS, the codespaces flag, and the private flag. Everything else hangs off those boundaries.
Main entry points: install.sh Install scripts · .chezmoiroot chezmoi source · run_onchange_after_bootstrap.sh.tmpl Post-apply hooks · dot_zshrc Shell stack
Components 19
Source State
chezmoi source tree and rendered machine state definitions
- chezmoi source · Rooted at home/ and rendered into user state by chezmoi
.chezmoiroot - Templates & data · Templates, data files, and naming conventions that parameterize host-specific output
home/.chezmoidata/mcp-servers.yaml - Path mapping · dot_, private_, executable_, and template suffixes encode paths and permissions
home/.chezmoiignore
Bootstrap
Entry scripts, platform setup, and delivery artifacts
- Install scripts · Fresh-machine entrypoints for Unix and Windows bootstrap flows
install.sh - Release artifacts · Published install scripts and container image outputs used by bootstrap
.github/workflows/release.yml - Package layer · Central package installation boundary for host software
home/Brewfile - Runtimes · Managed language/runtime versions installed after base packages are available
mise.toml - Post-apply hooks · Scripts that run after files and packages exist to finish setup
home/.chezmoiscripts/run_onchange_after_bootstrap.sh.tmpl
Workstation
Interactive shell, editor, terminal, and AI tooling
- Shell stack · zsh, Powerlevel10k, shell functions, and shell startup files
home/dot_config/zsh/dot_zshrc - Terminal config · Ghostty on macOS and WezTerm on Windows
home/dot_config/ghostty/config - Neovim stack · LazyVim-based Neovim configuration shared across environments
home/dot_config/nvim/init.lua - tmux · Unix session multiplexer configuration
home/dot_config/tmux/tmux.conf.local - AI tooling · OpenCode agents, commands, plugins, skills, and MCP wiring
home/dot_config/opencode/opencode.jsonc.tmpl - Identity & secrets · Git identity, GnuPG, Bitwarden wiring, and signing-related configuration
home/dot_gitconfig
Platforms
OS-specific branches and nested environments
- macOS · macOS-specific apps and integrations such as Finicky, Cursor, GnuPG, and Homebrew shell integration
home/dot_config/finicky.js - Windows · Native Windows config including PowerShell, PowerToys, Cursor, and WezTerm
home/Documents/PowerShell/Microsoft.PowerShell_profile.ps1 - WSL Ubuntu · Windows-managed Ubuntu environment bootstrapped separately and then synced with the same dotfiles
install.ps1 - Codespaces overlay · Prebuilt overlay image path used when CODESPACES=1 to skip full bootstrap work
Dockerfile
Quality
Validation and release pipeline
- Tests & release · Source-level tests, container validation, workflow builds, and provenance-controlled publishing
tests/source/chezmoi.bats
Connections 21
- Install scripts → chezmoi source: apply · Initializes chezmoi and renders home/ into the machine state
- chezmoi source → Templates & data: uses · Templates and data drive host-specific rendering
- chezmoi source → Path mapping: maps · Chezmoi naming conventions determine paths and permissions
- Install scripts → Package layer: installs · Bootstraps the host package manager and central package list
- Install scripts → Runtimes: provisions · Installs managed runtimes after base packages are available
- Install scripts → Post-apply hooks: triggers · Runs after initial apply to finish machine setup
- Post-apply hooks → Shell stack: primes · Prewarms shell caches and shell-related symlinks
- Post-apply hooks → Neovim stack: syncs · Refreshes editor plugins and related local state
- Shell stack → tmux: works with · Unix shell setup integrates with tmux and shell helpers
- Shell stack → Terminal config: renders in · Shell experience is tuned for the terminal emulator on each host
- Neovim stack → AI tooling: integrates · Editor workflow coexists with AI commands, agents, and MCP configuration
- AI tooling → Templates & data: parameterized by · AI/tooling config draws from template data and private flags
- Identity & secrets → Templates & data: separates · Identity and secret-aware configuration is modeled apart from general config
- macOS → Package layer: uses · macOS relies on Homebrew as the primary package boundary
- Windows → Package layer: uses · Windows uses its own package management path alongside native config
- Windows → WSL Ubuntu: spawns · Windows bootstrap provisions a nested Linux environment via WSL
- WSL Ubuntu → chezmoi source: applies · The same dotfiles are cloned and applied inside Ubuntu under WSL
- Codespaces overlay → Install scripts: optimizes · Codespaces mode short-circuits full bootstrap and extracts overlay layers
- Release artifacts → Codespaces overlay: publishes · Workflow builds and ships the container artifact for Codespaces
- Tests & release → Install scripts: tests · Source and container tests verify bootstrap behavior and overlays
- Tests & release → Release artifacts: gates · Release workflows and provenance checks govern published artifacts