|
1 | | -# CLAUDE.md |
2 | | - |
3 | | -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
4 | | - |
5 | | -## Overview |
6 | | - |
7 | | -This is a chezmoi-managed dotfiles repository for macOS and Linux machines. The source directory is `home/` which maps to the user's home directory. |
8 | | - |
9 | | -## Common Commands |
10 | | - |
11 | | -```bash |
12 | | -chezmoi apply # Apply dotfiles to home directory |
13 | | -chezmoi diff # Preview changes (scripts excluded by config) |
14 | | -chezmoi update # Pull latest and apply |
15 | | -chezmoi managed # List all managed files |
16 | | -chezmoi data # Show template data values |
17 | | -``` |
18 | | - |
19 | | -## Chezmoi Naming Conventions |
20 | | - |
21 | | -Files in `home/` use chezmoi prefixes: |
22 | | -- `dot_` → `.` (e.g., `dot_bashrc` → `.bashrc`) |
23 | | -- `private_` → file permissions 0600 |
24 | | -- `exact_` → directory is exact (unmanaged files are removed) |
25 | | -- `.tmpl` suffix → file is a Go template |
26 | | -- `run_before_`, `run_once_after_`, `run_onchange_after_` → script execution order |
27 | | - |
28 | | -## Template Variables |
29 | | - |
30 | | -Available in `.tmpl` files (defined in `home/.chezmoi.toml.tmpl`): |
31 | | - |
32 | | -| Variable | Description | |
33 | | -|----------|-------------| |
34 | | -| `.is_macos` / `.is_linux` | OS detection | |
35 | | -| `.has_gui` | Has graphical environment (all macOS, specific Linux hosts) | |
36 | | -| `.is_work` | Work machine vs personal | |
37 | | -| `.email`, `.fname`, `.ghuser` | Personal info from 1Password | |
38 | | -| `.copy_command` | Clipboard command (`pbcopy` or `xsel`) | |
39 | | - |
40 | | -## Architecture |
41 | | - |
42 | | -### Script Library (`home/.chezmoitemplates/dotfiles_bashlib.sh`) |
43 | | - |
44 | | -All chezmoi scripts should include this library for consistent output: |
45 | | -```bash |
46 | | -{{ template "dotfiles_bashlib.sh" . }} |
47 | | -``` |
48 | | - |
49 | | -Key functions: |
50 | | -- `dot::chezmoi_script_start "Script Name"` - Start a script with banner |
51 | | -- `dot::step::start "description"` - Begin a step |
52 | | -- `dot::step::done` / `dot::step::skipped` / `dot::step::fatal` - End a step |
53 | | -- `dot::has_command "cmd"` - Check if command exists |
54 | | -- `dot::os::setup` - Set up PATH for current OS |
55 | | - |
56 | | -### Bash Configuration (`home/exact_private_dot_bash.d/`) |
57 | | - |
58 | | -Modular bash config loaded by `.bashrc` in order: |
59 | | -1. `.bash.d/local/before/*` (untracked, machine-specific) |
60 | | -2. `.bash.d/*` (tracked modules) |
61 | | -3. `.bash.d/local/after/*` (untracked, machine-specific) |
62 | | - |
63 | | -Files are named with numeric prefixes for ordering (e.g., `010_functions_*.sh`). |
64 | | - |
65 | | -### ZSH Configuration (`home/dot_config/zsh/`) |
66 | | - |
67 | | -Modular zsh config loaded by `.zshrc` via `dot::bootstrap`: |
68 | | -1. `.config/zsh/zsh.d/local/before/*` (untracked, machine-specific) |
69 | | -2. `.config/zsh/zsh.d/*` (tracked modules) |
70 | | -3. `.config/zsh/zsh.d/local/after/*` (untracked, machine-specific) |
71 | | - |
72 | | -Files are named with numeric prefixes for ordering (e.g., `005_plugin_loader.zsh`). |
73 | | - |
74 | | -#### Bootstrap (`bootstrap.zsh`) |
75 | | - |
76 | | -The bootstrap defines core functions for the zsh startup lifecycle: |
77 | | -- `dot::bootstrap` - Entry point called from `.zshrc`, runs setup/source/cleanup |
78 | | -- `dot::source_file`, `dot::source_dir`, `dot::source_zsh_d` - Source helpers |
79 | | -- `dot::timing::setup/teardown` - Optional startup timing (`ZSH_TIME_STARTUP=1`) |
80 | | - |
81 | | -#### Deferred Cleanup (`dot::defer`) |
82 | | - |
83 | | -Register commands to run after all startup files have been sourced. Runs in LIFO order (last registered, first executed). The defer system cleans up itself on exit. |
84 | | - |
85 | | -```zsh |
86 | | -dot::defer "unset _my_temp_var" |
87 | | -dot::defer "unfunction my_helper" |
88 | | -``` |
89 | | - |
90 | | -All bootstrap functions, plugin loader state, and timing variables are cleaned up via `dot::defer` — none survive into the interactive session. |
91 | | - |
92 | | -#### ZSH Plugin System |
93 | | - |
94 | | -Data-driven plugin management without a framework. Plugins are defined in `home/.chezmoidata/zsh_plugins.yaml` and downloaded as chezmoi `git-repo` externals into `~/.config/zsh/plugins/`. |
95 | | - |
96 | | -**Data file** (`zsh_plugins.yaml`): |
97 | | -```yaml |
98 | | -# Single-plugin repo (name defaults to repo name): |
99 | | -- repo: zsh-users/zsh-autosuggestions |
100 | | - description: "Fish-like autosuggestions" |
101 | | - |
102 | | -# Multi-plugin repo (name defaults to last segment of path): |
103 | | -- repo: ohmyzsh/ohmyzsh |
104 | | - description: "Plugin source" |
105 | | - plugins: |
106 | | - - path: plugins/git |
107 | | - - path: plugins/docker |
108 | | - source: docker.plugin.zsh # only if non-standard |
109 | | -``` |
110 | | -
|
111 | | -**Key files:** |
112 | | -- `005_plugin_loader.zsh` - Defines `plug::load` and `plug::is_loaded` (static) |
113 | | -- `006_plugin_load.zsh.tmpl` - Generated `plug::load` calls from YAML |
114 | | -- `007_plugin_config.zsh` - Plugin configuration using `plug::is_loaded` guards |
115 | | -- `~/.config/zsh/plugins_ignore` - Local ignore list (one plugin name per line, `create_` managed) |
116 | | -- `zsh_plugins.toml.tmpl` - Generated chezmoi externals from YAML |
117 | | - |
118 | | -**Namespaces:** |
119 | | -- `dot::` - Bootstrap and startup lifecycle (defined in `bootstrap.zsh`) |
120 | | -- `plug::` - Plugin loading and state (defined in `005_plugin_loader.zsh`) |
121 | | - |
122 | | -Both namespaces are fully cleaned up after startup via `dot::defer`. |
123 | | - |
124 | | -### External Dependencies (`home/.chezmoiexternals/`) |
125 | | - |
126 | | -External tools pulled via chezmoi's external mechanism (git repos, archives). Each `.toml` file defines one or more externals. |
127 | | - |
128 | | -### Package Management |
129 | | - |
130 | | -- `home/.chezmoidata/packages.yml` - Package definitions for APT/Homebrew |
131 | | -- `home/.chezmoidata/package_specs.yml` - Software installation specs (with JSON schema validation) |
132 | | -- `Brewfile` - Homebrew bundle for macOS |
133 | | - |
134 | | -## Key Files |
135 | | - |
136 | | -- `home/.chezmoi.toml.tmpl` - Main chezmoi config, defines all template variables |
137 | | -- `home/.install-one-password.sh` - Pre-hook: installs 1Password CLI before template processing |
138 | | -- `home/.chezmoiscripts/` - Installation and setup scripts (ordered by prefix) |
139 | | -- `site/install` - Bootstrap script for fresh installations |
140 | | - |
141 | | -## Secrets |
142 | | - |
143 | | -All secrets are stored in 1Password and accessed via `onepasswordRead` in templates. Never hardcode sensitive values. |
144 | | - |
145 | | -## Git Commit Convention |
146 | | - |
147 | | -Commit messages follow the format: `Component: Short description` |
148 | | - |
149 | | -Examples from the repo: |
150 | | -- `Bashmarks: Migrate to XDG layout with dotfiles/local split` |
151 | | -- `Starship: Refactor to layered config with separate preset file` |
152 | | -- `Bash: Add iTerm2 shell integration via chezmoiexternal` |
153 | | - |
154 | | -Do not add `Co-Authored-By` lines. |
155 | | - |
156 | | -## Chezmoi Documentation |
157 | | - |
158 | | -When you need chezmoi information, use these sources in order: |
159 | | - |
160 | | -1. **Built-in knowledge** - Claude has extensive chezmoi knowledge from training |
161 | | -2. **`chezmoi help <command>`** - Run via Bash for command-specific details |
162 | | -3. **Online docs** - Fetch from `https://www.chezmoi.io/` (note: may reference newer chezmoi versions than installed) |
| 1 | +@AGENTS.md |
0 commit comments