This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Chezmoi-based cross-platform dotfiles. Primary platform: macOS (Apple Silicon), with Linux/NixOS support. Template-driven configuration with 30+ conditional features. Shell startup ~386ms via caching and lazy-loading.
make install # chezmoi init --apply (fresh machine)
make update # Pull remote + chezmoi apply
make diff # Preview pending chezmoi changes
chezmoi apply # Apply local source changes to home directory
chezmoi apply --force # Skip prompts for modified target files
make lint # shellcheck on scripts/ and utils/
make doctor # Health check (32 checks across tools, config, security)
make perf # 5-run shell startup benchmark
make perf-report # Bare vs configured startup breakdown
make test # Test suite (zsh syntax, module loading)
make brew-install # Install Brewfile packages
make brew-dump # Update Brewfile from current system
make brew-check # Check for packages not in Brewfile
make brew-cleanup # Remove packages not in Brewfile
make dashboard # Service status dashboard (CLI)
make dashboard-watch # Dashboard with auto-refresh
make setup-secrets # Install 1Password, AWS CLI, Infisical, Tailscale
make rotate-keys # SSH key rotation via 1Password + Tailscale sync
make theme-generate # Generate all tool configs from unified theme
make lazy-load-stats # Show lazy loading statsSource directory: home/ (set in chezmoi.toml as sourceDir). Chezmoi maps home/dot_foo -> ~/.foo, home/private_dot_config/ -> ~/.config/.
Template system: Files ending in .tmpl use Go template syntax. All boolean flags live in chezmoi.toml under [data]:
# Identity: name, email, github, gpg_signing_key, age_recipient, brewPrefix
# Shell: starship, ohmyzsh, oh_my_zsh_theme, oh_my_zsh_plugins
# Tools: mise, rust, elixir, erlang, lua, direnv, devenv, nix
# Services: tailscale, onepassword, aws, infisical, orbstack
# macOS: paperwm, raycast, llvm, postgres, psql
# Web3: foundry, huff, solana
# Apps: takopi, work, personal
# Theme: [data.theme] -- full Synthwave84 palette (bg, fg, accent, ANSI colors)
Use in templates: {{- if .rust -}}...{{- end -}}. Use {{- -}} to trim whitespace.
Template strictness: [template] options = ["missingkey=error"] -- referencing an undefined key is a hard error. Always check that a flag exists in chezmoi.toml before using it in a template.
Run-onchange scripts (auto-execute on chezmoi apply):
run_onchange_after_brew-bundle.sh.tmpl-- runsbrew bundle installwhen Brewfile hash changesrun_onchange_after_mise-install.sh.tmpl-- runsmise installwhen mise config changesrun_onchange_after_reload-hammerspoon.sh.tmpl-- reloads Hammerspoon on config change (macOS)run_onchange_after_sync-skills.sh.tmpl-- symlinks skills from~/.agents/skills/to~/.claude/skills/
Age encryption: Sensitive files use encrypted_ prefix. Decryption key is stored in 1Password (secure note "AGE-SECRET-KEY" in Employee vault) and accessed via ~/.config/chezmoi/age-op-decrypt.sh wrapper -- no plaintext key on disk. To edit encrypted templates, decrypt with age -d -i <(op read "op://Employee/AGE-SECRET-KEY/notesPlain" | grep "^AGE-SECRET-KEY-"), edit, re-encrypt with age -r "<recipient>", verify with chezmoi diff. chezmoi re-add does NOT work for encrypted files.
Encrypted files:
home/dot_ssh/encrypted_config.tmpl-- SSH config with Tailscale hosts, 1Password SSH agent on macOShome/dot_zsh/core/encrypted_secrets.zsh-- 1Password/AWS/Infisical integrationhome/dot_takopi/encrypted_takopi.toml-- takopi bot config
Entry: dot_zshrc.tmpl -> sources ~/.zsh/modules.zsh
modules.zsh auto-sources in order:
core/*.zsh(alphabetically: config, lazy-loading, package-managers, paths, prompt, secrets, ssh, tools, xdg)core/platforms/*.zsh(macos.zsh or linux.zsh)aliases/*.zshfunctions/*.zshenv.zsh(explicit, not wildcard)
Performance-critical patterns (don't break these):
compinit -Cwhen.zcompdumpis fresh (<24h), fullcompinitonly when stale- Starship init cached to
$XDG_CACHE_HOME/zsh-completions/starship-init.zsh(24h TTL) - Tool completions (mise, chezmoi) cached via
_cache_completion()helper (24h TTL) - Oh My Zsh conditionally skipped when
starship = true(saves ~1000ms) - Fastfetch deferred to one-shot
precmdhook (runs after first prompt, not before) modules.zshsourcesenv.zshexplicitly -- do NOT use root-level wildcards (stale files caused 1357ms regression)
PATH management: core/paths.zsh.tmpl defines a PATH_REGISTRY associative array and build_path() function. All PATH additions go through add_to_path() which checks directory existence. Registry keys: base, macos_brew, linux_local, mise, rust, pnpm_macos, pnpm_linux, pipx, npm_global, foundry, huff, solana, llvm, postgres_homebrew, postgres_app, erlang, elixir_mix, lua_luarocks, nix_profile.
Scripts source scripts/utils/simple-init.sh for: set -euo pipefail, color vars, log_info/log_success/log_error/log_warning/log_debug, auto-detected $DOTFILES_ROOT. Logging is centralized in scripts/utils/logging.sh (sourced by simple-init.sh). Supports QUIET=true to suppress info/success and DEBUG=true for debug output. Also provides short aliases: info, success, warn, error.
Shared constants from scripts/utils/constants.sh: exit codes (EXIT_SUCCESS through EXIT_TIMEOUT), identity vars from chezmoi data (GITHUB_USER, USER_NAME, USER_EMAIL, AGE_RECIPIENT), infrastructure (OP_VAULT, TAILSCALE_USER), platform detection (PLATFORM, ARCH).
Setup scripts follow the pattern: scripts/setup/setup-<tool>.sh with subcommands (install, status, config). Add a Makefile target with ## comment for make help discoverability.
Commits run: trailing-whitespace, end-of-file-fixer, check-yaml, check-added-large-files (500KB), check-merge-conflict, shellcheck (error level, -x to follow sources, excludes home/dot_zsh/*.zsh), black (Python), prettier (JSON/YAML/Markdown). Encrypted files (encrypted_*) are excluded from whitespace hooks.
Single source of truth: [data.theme] in chezmoi.toml (Synthwave84 palette). Templates reference colors as {{ .theme.bg }}, {{ .theme.accent }}, etc. Applied to: fzf (tools.zsh.tmpl), Starship (starship.toml.tmpl), Hammerspoon alerts. Static theme files in config/theme/synthwave84.toml for tools that can't use chezmoi templates.
New alias: Add to home/dot_zsh/aliases/dev.zsh
New conditional tool:
- Add flag to
chezmoi.toml:mytool = true - Gate in templates:
{{- if .mytool -}}...{{- end -}}
New setup script:
- Create
scripts/setup/setup-mytool.sh(sourcesimple-init.sh, add subcommands) - Add Makefile target with
## comment - Add to
.PHONYline
New PATH entry: Add key to PATH_REGISTRY in paths.zsh.tmpl, add conditional add_to_path call in build_path()
Local skills (ethskills/, solidity-audit/, noir/) provide offline Ethereum, Solidity, and ZK knowledge. For supplemental or latest info, fetch from ETHSkills live sources (URLs listed in solidity-audit/live-sources.md).
| Live Skill | URL | Use Case |
|---|---|---|
| Security | ethskills.com/security/SKILL.md |
Reentrancy, oracles, vault inflation, MEV |
| Tools | ethskills.com/tools/SKILL.md |
Blockscout MCP, Foundry, abi.ninja |
| L2s | ethskills.com/l2s/SKILL.md |
Cross-chain, bridging, L2 economics |
| Standards | ethskills.com/standards/SKILL.md |
ERC-8004, EIP-7702, token standards |
| Gas | ethskills.com/gas/SKILL.md |
Current costs (mainnet ~$0.002, L2 ~$0.002) |
Blockscout MCP: Configured in ~/.mcp.json. Provides type-safe blockchain data queries (balances, tokens, NFTs, contracts) across multiple chains via Model Context Protocol.
Managed via ~/.mcp.json (chezmoi template: home/dot_mcp.json.tmpl). Toggle in chezmoi.toml, then chezmoi apply.
| Server | Flag | Transport | Notes |
|---|---|---|---|
| context7 | always on | stdio | Library docs via npx |
| blockscout | always on | http | Blockchain data queries |
| datadog | datadog |
http/OAuth | us5.datadoghq.com, no secrets |
| sentry | sentry |
http/OAuth | mcp.sentry.dev, no secrets |
| signoz | signoz |
stdio | API key from 1Password at runtime |
Datadog: Enable datadog = true in chezmoi.toml, chezmoi apply. OAuth via browser.
Sentry: Enable sentry = true in chezmoi.toml, chezmoi apply. OAuth via browser.
SigNoz setup:
make setup-signoz-mcp(builds from source, requires Go)- Store API key:
op item create --vault Employee --category login --title "SigNoz API Key" credential=<key> - Set
signoz = truein chezmoi.toml,chezmoi apply
Skills are sourced from DROOdotFOO/agent-skills and pulled via home/.chezmoiexternal.toml on chezmoi apply. Deployed to ~/.agents/skills/ and symlinked to ~/.claude/skills/ by run_onchange_after_sync-skills.sh.tmpl.
Code pattern skills -- language-specific examples and idioms:
| Skill | Triggers on |
|---|---|
| claude-api | anthropic imports, SDK usage |
| droo-stack | Elixir, TS, Go, Rust, C, Zig, Python, Lua, Shell, Noir, Chezmoi |
| raxol | Raxol TUI/agent imports, headless/MCP tools |
| design-ux | Component design, layout, tokens, accessibility, TUI aesthetics, DESIGN.md |
| nix | .nix files, flakes, NixOS, Home Manager, agent-skills packaging, rigup |
| native-code | NIFs (C/Rust), SIMD (Zig), erl_nif.h, Rustler, BEAM native boundary |
Web3 skills -- blockchain development, auditing, and data:
| Skill | Triggers on |
|---|---|
| ethskills | Ethereum tooling, EIP/ERC standards, framework selection |
| solidity-audit | .sol files, foundry.toml, auditing, security review |
| noir | .nr files, Nargo.toml, ZK circuits, Aztec contracts/security/e2e testing |
| blockscout | On-chain data queries, contract state, token balances, ENS, NFT holdings |
| coingecko | Token prices, market caps, DEX pools, trending tokens, price history |
MCP-companion skills -- reference docs for MCP agent tools:
| Skill | Triggers on |
|---|---|
| autoresearch | Experiment status, "run another iteration", /autoresearch |
| patchbot | Outdated dependencies, "update deps", /patchbot |
| prepper | Project briefings, "catch me up", "prep me", /prepper |
| sentinel | Contract monitoring, on-chain alerts, suspicious transactions |
| watchdog | Repo health, stale PRs, CI status, security advisories |
Workflow skills (40 total) -- architect, code-review, tdd, focused-fix, adversarial-reviewer, prd-to-plan, prd-to-issues, release, and more. Each has a SKILL.md with trigger conditions.
Skills provide detailed incorrect/correct code examples. CLAUDE.md provides preferences and philosophy. To add a new skill: add to the agent-skills repo, push to main, then chezmoi apply --refresh-externals.
Skills map -- how skills relate:
droo-stack (code patterns)
/ | \ \ \
Elixir TS/JS Go/Rust C/Zig Py/Lua/Shell
| | |
raxol design-ux native-code
(TUI) (UI/UX) (NIFs + SIMD)
\ /
terminal aesthetics
ethskills (ecosystem)
/ | \
solidity noir blockscout -- coingecko
-audit (ZK) (on-chain) (markets)
(contracts) |
sentinel (monitor)
nix (Nix ecosystem)
/ | \
flakes NixOS Home Manager
\
agent-skills packaging
MCP companions (agent tools)
/ | \ \ \
auto patch prepper sentinel watchdog
research bot (brief) (chain) (repo)
Each skill has "See also" cross-references in its SKILL.md.
- Shell: bash with
set -euo pipefail, shellcheck compliant, quote all variables - Use
[[ ]]over[ ],$((expr))over((expr))(the latter fails underset -ewhen result is 0) - Guard external commands that may return non-zero:
grep ... || true,command -v ... &>/dev/null - Chezmoi templates:
{{- -}}to trim whitespace, use.chezmoi.homeDirnot~