# chipwolf/dotfiles architecture

> Architecture diagram of the GitHub repository chipwolf/dotfiles, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chipwolf/dotfiles
- Repository: https://github.com/chipwolf/dotfiles

## Overview

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`](https://github.com/chipwolf/dotfiles/blob/main/install.sh) (Install scripts), [`.chezmoiroot`](https://github.com/chipwolf/dotfiles/blob/main/.chezmoiroot) (chezmoi source), [`home/.chezmoiscripts/run_onchange_after_bootstrap.sh.tmpl`](https://github.com/chipwolf/dotfiles/blob/main/home/.chezmoiscripts/run_onchange_after_bootstrap.sh.tmpl) (Post-apply hooks), [`home/dot_config/zsh/dot_zshrc`](https://github.com/chipwolf/dotfiles/tree/main/home/dot_config/zsh/dot_zshrc) (Shell stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_source["Source State"]
  node_chezmoi_source["chezmoi source<br/>source tree<br/>[.chezmoiroot]"]
  node_template_data["Templates & data<br/>render inputs<br/>[mcp-servers.yaml]"]
  node_file_conventions["Path mapping<br/>chezmoi conventions<br/>[.chezmoiignore]"]
end

subgraph group_bootstrap["Bootstrap"]
  node_bootstrap_scripts["Install scripts<br/>bootstrap entrypoints<br/>[install.sh]"]
  node_release_artifacts["Release artifacts<br/>delivery bundle<br/>[release.yml]"]
  node_package_layer["Package layer<br/>host packages"]
  node_runtime_layer["Runtimes<br/>toolchain provisioning<br/>[mise.toml]"]
  node_post_apply["Post-apply hooks<br/>orchestration"]
end

subgraph group_workstation["Workstation"]
  node_shell_surface["Shell stack<br/>interactive shell"]
  node_terminal_surface["Terminal config<br/>terminal emulator"]
  node_editor_surface["Neovim stack<br/>editor config<br/>[init.lua]"]
  node_multiplexer["tmux<br/>session mux<br/>[tmux.conf.local]"]
  node_ai_tooling["AI tooling<br/>agent config"]
  node_secrets_identity["Identity & secrets<br/>credential config"]
end

subgraph group_platforms["Platforms"]
  node_macos_branch["macOS<br/>os branch<br/>[finicky.js]"]
  node_windows_branch["Windows<br/>os branch"]
  node_wsl_nested["WSL Ubuntu<br/>nested linux env<br/>[install.ps1]"]
  node_codespaces_overlay["Codespaces overlay<br/>container path"]
end

subgraph group_quality["Quality"]
  node_validation_release["Tests & release<br/>quality pipeline<br/>[chezmoi.bats]"]
end

node_bootstrap_scripts -->|"apply"| node_chezmoi_source
node_chezmoi_source -->|"uses"| node_template_data
node_chezmoi_source -->|"maps"| node_file_conventions
node_bootstrap_scripts -->|"installs"| node_package_layer
node_bootstrap_scripts -->|"provisions"| node_runtime_layer
node_bootstrap_scripts -->|"triggers"| node_post_apply
node_post_apply -->|"primes"| node_shell_surface
node_post_apply -->|"syncs"| node_editor_surface
node_shell_surface -->|"works with"| node_multiplexer
node_shell_surface -->|"renders in"| node_terminal_surface
node_editor_surface -->|"integrates"| node_ai_tooling
node_ai_tooling -->|"parameterized by"| node_template_data
node_secrets_identity -->|"separates"| node_template_data
node_macos_branch -->|"uses"| node_package_layer
node_windows_branch -->|"uses"| node_package_layer
node_windows_branch -->|"spawns"| node_wsl_nested
node_wsl_nested -->|"applies"| node_chezmoi_source
node_codespaces_overlay -->|"optimizes"| node_bootstrap_scripts
node_release_artifacts -->|"publishes"| node_codespaces_overlay
node_validation_release -->|"tests"| node_bootstrap_scripts
node_validation_release -->|"gates"| node_release_artifacts

click node_chezmoi_source "https://github.com/chipwolf/dotfiles/blob/main/.chezmoiroot"
click node_template_data "https://github.com/chipwolf/dotfiles/blob/main/home/.chezmoidata/mcp-servers.yaml"
click node_file_conventions "https://github.com/chipwolf/dotfiles/blob/main/home/.chezmoiignore"
click node_bootstrap_scripts "https://github.com/chipwolf/dotfiles/blob/main/install.sh"
click node_release_artifacts "https://github.com/chipwolf/dotfiles/blob/main/.github/workflows/release.yml"
click node_package_layer "https://github.com/chipwolf/dotfiles/tree/main/home/Brewfile"
click node_runtime_layer "https://github.com/chipwolf/dotfiles/blob/main/mise.toml"
click node_post_apply "https://github.com/chipwolf/dotfiles/blob/main/home/.chezmoiscripts/run_onchange_after_bootstrap.sh.tmpl"
click node_shell_surface "https://github.com/chipwolf/dotfiles/tree/main/home/dot_config/zsh/dot_zshrc"
click node_terminal_surface "https://github.com/chipwolf/dotfiles/tree/main/home/dot_config/ghostty/config"
click node_editor_surface "https://github.com/chipwolf/dotfiles/blob/main/home/dot_config/nvim/init.lua"
click node_multiplexer "https://github.com/chipwolf/dotfiles/blob/main/home/dot_config/tmux/tmux.conf.local"
click node_ai_tooling "https://github.com/chipwolf/dotfiles/blob/main/home/dot_config/opencode/opencode.jsonc.tmpl"
click node_secrets_identity "https://github.com/chipwolf/dotfiles/tree/main/home/dot_gitconfig"
click node_macos_branch "https://github.com/chipwolf/dotfiles/blob/main/home/dot_config/finicky.js"
click node_windows_branch "https://github.com/chipwolf/dotfiles/blob/main/home/Documents/PowerShell/Microsoft.PowerShell_profile.ps1"
click node_wsl_nested "https://github.com/chipwolf/dotfiles/blob/main/install.ps1"
click node_codespaces_overlay "https://github.com/chipwolf/dotfiles/tree/main/Dockerfile"
click node_validation_release "https://github.com/chipwolf/dotfiles/blob/main/tests/source/chezmoi.bats"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_chezmoi_source,node_template_data,node_file_conventions toneBlue
class node_bootstrap_scripts,node_release_artifacts,node_package_layer,node_runtime_layer,node_post_apply toneAmber
class node_shell_surface,node_terminal_surface,node_editor_surface,node_multiplexer,node_ai_tooling,node_secrets_identity toneMint
class node_macos_branch,node_windows_branch,node_wsl_nested,node_codespaces_overlay toneRose
class node_validation_release toneIndigo
```

## Components

### Source State

chezmoi source tree and rendered machine state definitions

- [chezmoi source](https://github.com/chipwolf/dotfiles/blob/main/.chezmoiroot): source tree · Rooted at home/ and rendered into user state by chezmoi · `.chezmoiroot`
- [Templates & data](https://github.com/chipwolf/dotfiles/blob/main/home/.chezmoidata/mcp-servers.yaml): render inputs · Templates, data files, and naming conventions that parameterize host-specific output · `home/.chezmoidata/mcp-servers.yaml`
- [Path mapping](https://github.com/chipwolf/dotfiles/blob/main/home/.chezmoiignore): chezmoi conventions · dot_, private_, executable_, and template suffixes encode paths and permissions · `home/.chezmoiignore`

### Bootstrap

Entry scripts, platform setup, and delivery artifacts

- [Install scripts](https://github.com/chipwolf/dotfiles/blob/main/install.sh): bootstrap entrypoints · Fresh-machine entrypoints for Unix and Windows bootstrap flows · `install.sh`
- [Release artifacts](https://github.com/chipwolf/dotfiles/blob/main/.github/workflows/release.yml): delivery bundle · Published install scripts and container image outputs used by bootstrap · `.github/workflows/release.yml`
- [Package layer](https://github.com/chipwolf/dotfiles/tree/main/home/Brewfile): host packages · Central package installation boundary for host software · `home/Brewfile`
- [Runtimes](https://github.com/chipwolf/dotfiles/blob/main/mise.toml): toolchain provisioning · Managed language/runtime versions installed after base packages are available · `mise.toml`
- [Post-apply hooks](https://github.com/chipwolf/dotfiles/blob/main/home/.chezmoiscripts/run_onchange_after_bootstrap.sh.tmpl): orchestration · 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](https://github.com/chipwolf/dotfiles/tree/main/home/dot_config/zsh/dot_zshrc): interactive shell · zsh, Powerlevel10k, shell functions, and shell startup files · `home/dot_config/zsh/dot_zshrc`
- [Terminal config](https://github.com/chipwolf/dotfiles/tree/main/home/dot_config/ghostty/config): terminal emulator · Ghostty on macOS and WezTerm on Windows · `home/dot_config/ghostty/config`
- [Neovim stack](https://github.com/chipwolf/dotfiles/blob/main/home/dot_config/nvim/init.lua): editor config · LazyVim-based Neovim configuration shared across environments · `home/dot_config/nvim/init.lua`
- [tmux](https://github.com/chipwolf/dotfiles/blob/main/home/dot_config/tmux/tmux.conf.local): session mux · Unix session multiplexer configuration · `home/dot_config/tmux/tmux.conf.local`
- [AI tooling](https://github.com/chipwolf/dotfiles/blob/main/home/dot_config/opencode/opencode.jsonc.tmpl): agent config · OpenCode agents, commands, plugins, skills, and MCP wiring · `home/dot_config/opencode/opencode.jsonc.tmpl`
- [Identity & secrets](https://github.com/chipwolf/dotfiles/tree/main/home/dot_gitconfig): credential config · Git identity, GnuPG, Bitwarden wiring, and signing-related configuration · `home/dot_gitconfig`

### Platforms

OS-specific branches and nested environments

- [macOS](https://github.com/chipwolf/dotfiles/blob/main/home/dot_config/finicky.js): os branch · macOS-specific apps and integrations such as Finicky, Cursor, GnuPG, and Homebrew shell integration · `home/dot_config/finicky.js`
- [Windows](https://github.com/chipwolf/dotfiles/blob/main/home/Documents/PowerShell/Microsoft.PowerShell_profile.ps1): os branch · Native Windows config including PowerShell, PowerToys, Cursor, and WezTerm · `home/Documents/PowerShell/Microsoft.PowerShell_profile.ps1`
- [WSL Ubuntu](https://github.com/chipwolf/dotfiles/blob/main/install.ps1): nested linux env · Windows-managed Ubuntu environment bootstrapped separately and then synced with the same dotfiles · `install.ps1`
- [Codespaces overlay](https://github.com/chipwolf/dotfiles/tree/main/Dockerfile): container path · Prebuilt overlay image path used when CODESPACES=1 to skip full bootstrap work · `Dockerfile`

### Quality

Validation and release pipeline

- [Tests & release](https://github.com/chipwolf/dotfiles/blob/main/tests/source/chezmoi.bats): quality pipeline · Source-level tests, container validation, workflow builds, and provenance-controlled publishing · `tests/source/chezmoi.bats`

## Connections

- 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
