Dotfiles

The version-controlled home for my Mac's configuration files. When I set up a new machine, this is what I clone to get it back the way I like it.

It pairs with bjardon/fleet, which provisions Linux machines and their account profiles. This repository owns my Mac setup.

What's tracked

Each configuration area keeps its own files and restore steps.

• Skills. Vendored agent skills, symlinked into place by an installer.
• Global agent instructions. Personal Codex AGENTS.md and Claude Code CLAUDE.md files, with a preview and backup installer.
• SSH hosts. The devbox, oxpbox, and synobox aliases, included from ~/.ssh/config.
• Zsh. ~/.zshenv, ~/.zprofile, and ~/.zshrc, with Oh My Zsh pinned to a commit.
• Distrusted CA roots. Compromised roots to remove from /etc/ssl/cert.pem, with a shell startup check that warns when a macOS update puts one back.
• Git. ~/.gitconfig, with a preview and backup installer.
• Tools. A Brewfile, an app list for a fresh Mac, and pnpm global packages, with a command that reports what's drifted.

Skills

Nine skills are checked into Git. The original seven match the versions installed on this Mac; the two personal skills are pinned to their upstream commits.

Source	Selected skills
pstack	blast-radius, bro, how, unslop, why
Matt Pocock	codebase-design, writing-for-agents
Bruno Jardon	discuss, experiment

The manifest records exact commits, file checksums, licenses, and destination folders. The personal repository declares no upstream license; its entries use NOASSERTION with a provenance note for bjardon/skills. Skill policy describes what belongs here. CLI-managed skills records Composio and Railway. gh-cli, linear-cli, and find-skills are not selected. Existing unselected skills are left alone.

Restoring skills on a Mac

Install Git, Node.js 22 or newer, and pnpm 11.5.2 first. Clone this repository into a permanent location:

git clone git@github.com:bjardon/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
pnpm install --frozen-lockfile
pnpm run check
pnpm run skills install
pnpm run skills install --apply

install previews every link without writing files. --apply links the vendored skills into ~/.agents/skills and ~/.claude/skills. Existing files, directories, and conflicting or broken links are moved into ~/.local/state/dotfiles/backups/<run-id>/, preserving their relative home paths. Already-correct links are left alone. No downloads or upstream installers run. Restart your coding tools after applying.

Keep the checkout in place because installed links point into it. If you move it, run the installer from its new location. Run Composio and Railway's documented restore commands separately after installing their CLIs.

Recovery

Each changed item prints its backup path. To undo a replacement, remove only the new skill symlink, then move the matching backup to the original path. For example, replace <run-id> with the backup directory printed by the installer:

unlink ~/.agents/skills/bro
mv ~/.local/state/dotfiles/backups/<run-id>/.agents/skills/bro ~/.agents/skills/bro

For a newly created link with no backup, unlink is sufficient. Backups are never pruned automatically. An interrupted run can leave some links applied; rerun the preview to inspect the remaining work or restore the printed backups.

Maintaining the selection

Edit skills/manifest.json to change the list or destination folders. Adding or updating a skill requires copying the complete upstream skill directory at an explicit commit, retaining its license, and updating its source path, tree hash, and SHA-256 file inventory. Review the diff and run the checks below before applying. Keep local modifications explicit in Git; do not silently refresh from an upstream branch or run skills.sh updates on these managed skills.

Removing a manifest entry stops managing it; it does not delete its existing links. Remove those links explicitly before deleting its vendored directory. Credentials, company-specific settings, plugin caches, and agent session history stay outside this repository.

The installer and tests are TypeScript, run through tsx. Run pnpm install --frozen-lockfile after cloning to install the locked development tools. No build step is required. tsx executes TypeScript without type checking, so pnpm run check and pnpm test both run strict tsc --noEmit checks first. pnpm run typecheck checks types alone. JSON manifests are validated at runtime before any filesystem changes.

Validation

pnpm run check
pnpm test

Tests use temporary homes for preview, installation, backups, repeat runs, and failure cases. They do not alter the current user's skill installation.

Restoring global agent instructions

After pnpm install --frozen-lockfile, follow the agent instructions guide:

pnpm run agents install
pnpm run agents install --apply

This links shared instructions into ~/.agents/AGENTS.md, with an additional ~/.codex/AGENTS.md link for Codex. ~/.claude/CLAUDE.md imports the shared file and adds Claude-specific instructions. Existing items are backed up before replacement. Start new agent sessions after applying. Restore skills too so Claude can use unslop.

Restoring SSH hosts

After pnpm install --frozen-lockfile, follow the SSH hosts guide:

pnpm run ssh install
pnpm run ssh install --apply

This links ~/.ssh/config.d/devbox.conf and adds an Include for it at the top of ~/.ssh/config, backing up the existing config first. Other hosts in ~/.ssh/config stay unmanaged.

Restoring zsh

After pnpm install --frozen-lockfile, follow the zsh guide. Clone Oh My Zsh at the commit in zsh/oh-my-zsh-commit, then:

pnpm run zsh install
pnpm run zsh install --apply

This links ~/.zshenv, ~/.zprofile, and ~/.zshrc into this checkout, backing up the existing files first. Shell history stays local.

Removing distrusted CA roots

After pnpm install --frozen-lockfile, follow the CA roots guide:

pnpm run ca install
pnpm run ca install --apply

This removes the listed roots from /etc/ssl/cert.pem with sudo, after backing up the file. Restore zsh too, so new shells warn when a macOS update restores a root.

Restoring Git config

After pnpm install --frozen-lockfile, follow the Git guide:

pnpm run git install
pnpm run git install --apply

This links ~/.gitconfig into this checkout, backing up the existing file first.

Restoring tools

After installing Homebrew, follow the tools guide:

brew bundle --file tools/Brewfile
brew bundle --file tools/Brewfile.apps
xargs -n 1 pnpm add -g < tools/pnpm-globals
pnpm run tools status

Some apps have no cask, so the guide lists the ones to get by hand.