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 and oxpbox aliases, included from ~/.ssh/config.
• Zsh. ~/.zshenv, ~/.zprofile, and ~/.zshrc, with Oh My Zsh pinned to a commit.

Skills

Twenty-six skills are checked into Git. The original seven match the versions installed on this Mac; the seventeen SynoraStudio skills and 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
SynoraStudio	adopt-project, babysit, build, design-interface, grill, handoff, implement, init-agent-os, intake, maintain-language, maintain-living-docs, map-decisions, prototype, reconcile-tracker, review, write-adr, write-issues

The manifest records exact commits, file checksums, licenses, and destination folders. SynoraStudio skills use the upstream MIT license. 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.