Clone Config

clone-config — chezmoi dotfile workflow

chezmoi gives dotfiles a single source of truth: one Git repo, applied to every machine with one command. Files in the source dir are named with prefixes (dot_, private_) that map to locations in $HOME. You edit the source, apply to $HOME; the target is always derived, never the authority.

The patterns below reflect the actual setup in ~/projects/dotfiles: .zshrc, .zprofile, .p10k.zsh, .tmux.conf, Yazi config, Kaku config, Ghostty config, a Brewfile, and an install script that re-runs whenever the Brewfile hash changes.

Bootstrap a fresh machine

# 1. Install Homebrew (if missing)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Install chezmoi and apply the dotfiles repo
brew install chezmoi
chezmoi init --apply git@github.com:YOUR_USER/dotfiles.git

One chezmoi init --apply does everything:

1. Writes all tracked source files to $HOME
2. Clones externals (oh-my-zsh, fzf-tab) declared in .chezmoiexternal.toml
3. Runs run_onchange_install-packages.sh → brew bundle, uv tools, npm globals, yazi plugins

After that the machine is fully provisioned. No separate install scripts to remember, no manual symlinks.

Layout conventions

Key convention: dot_ → leading dot, private_ → restricted permissions. Both prefixes can be combined: private_dot_ssh/ → ~/.ssh/ (mode 0700).

Daily workflow

The source repo lives at ~/.local/share/chezmoi by default. chezmoi cd is the fastest way in; treat it like any Git repo once there.

Adding a new file

# 1. Tell chezmoi to track the file (copies it into source)
chezmoi add ~/some/config

# 2. Commit from inside the source repo
chezmoi cd
git add -A && git commit -m "track some/config"
git push  # or: open a PR if the dotfiles repo enforces review

After git push, any other machine running chezmoi update picks up the file.

The run_onchange installer pattern

This is the high-leverage part of the setup. A single templated script orchestrates all package management and re-runs automatically whenever its content changes — including whenever the embedded Brewfile hash changes.

Actual content of run_onchange_install-packages.sh.tmpl:

#!/usr/bin/env bash
# Re-runs whenever this file changes (including Brewfile hash below).
# Manages: homebrew, uv tools, npm globals, yazi plugins.
set -euo pipefail

# Brewfile hash: {{ include "Brewfile" | sha256sum }}

echo "==> brew bundle"
brew bundle --no-lock --file="{{ joinPath .chezmoi.sourceDir "Brewfile" }}"

echo "==> uv tools"
for tool in claude-code-telegram fb-idb specify-cli; do
    uv tool install --quiet "$tool" || true
done

echo "==> npm globals (requires an fnm-managed node on PATH)"
if command -v npm >/dev/null 2>&1; then
    npm install -g --silent \
        @cometix/ccline \
        @openai/codex \
        agent-browser \
        clawhub \
        eas-cli \
        gitnexus \
        mcporter \
        openclaw \
        pnpm || true
fi

echo "==> yazi plugins"
if command -v ya >/dev/null 2>&1; then
    ya pkg add yazi-rs/plugins:smart-enter || true
fi

echo "==> done"

Key mechanics:

• Hash trigger: the comment {{ include "Brewfile" | sha256sum }} is a chezmoi template expression. When Brewfile changes, the rendered script content changes → chezmoi detects a diff → re-runs the script on next chezmoi apply.
• One orchestrator: brew, uv, npm, and yazi plugins — all in one place. No separate bootstrap scripts to remember.
• Idempotent: every tool install uses || true, so partial failures don't abort the whole run. brew bundle itself is idempotent.
• No .tmpl at runtime: chezmoi renders the template before running; the running script is plain bash.

Brewfile refresh cycle

When you install new packages and want them tracked:

chezmoi cd
brew bundle dump --force --file=Brewfile
git add Brewfile && git commit -m "refresh Brewfile from <machine-name>"
git push

On the next chezmoi apply (or chezmoi update) on any machine, the Brewfile hash in the install script changes → script re-runs → brew bundle installs any new packages.

Never hand-edit the Brewfile to add packages you haven't actually installed — brew bundle dump --force captures the live state of the machine, which is the truth.

Composition with other skills

Doppler (skills/doppler/SKILL.md)

The chezmoi-managed dot_zshrc is where the Doppler keychain bootstrap lives:

export DOPPLER_TOKEN="$(security find-generic-password -a "$USER" -s doppler-cli-token -w 2>/dev/null)"

This line is tracked in source and applied to every machine. The actual secret (the Personal Token) is NOT in dotfiles — it lives in the macOS Keychain and must be seeded manually on each machine with:

security add-generic-password -a "$USER" -s doppler-cli-token -w 'dp.pt.xxx' -U

That separation is intentional: dotfiles carry the bootstrap pattern, Doppler carries the actual secrets. Never put real tokens, API keys, or passwords in dotfiles source.

flight-deck (landing / takeoff)

Useful for wrapping up dotfile PRs — landing commits the Brewfile refresh or config addition, takeoff resumes from a clean state on a new machine.

Anti-patterns

Quick Reference