dotfiles

Life is like a hurricane here in Shellville
Needed me a toolchain to wrangle this shell hell
A syncing mystery with versioned history
Dotfiles! (Woo-oo!)
This repo's my attempt to repro
Dotfiles! (Woo-oo!)
Configs, options, run commands, and
profiles! (Woo-oo!)

Supported Shells

• zsh 5.9
• bash 3.2 (required for MacOS Sonoma)
• bash 4.0 (Fedora)

Prerequisites

Required

chezmoi

sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply $GITHUB_USERNAME

Recommended

Package Manager: Homebrew

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

Plugin Manager, zsh: Antidote

brew install antidote

Prompt: Starship

curl -sS https://starship.rs/install.sh | sh

Shell History: Atuin

# if it isn't already installed via homebrew, as it is in Bazzite-DX...
curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh | sh
atuin setup

JSON Parser: jqlang/jq

brew install jq

Optional

YAML Parser: mikefarah/yq

brew install yq

Environment Management: direnv

Faster Text Search: ripgrep

Agent instructions

Global, cross-project agent guidance lives in ~/.agents/AGENTS.md (chezmoi source: dot_agents/AGENTS.md). This is a personal convention — there is no cross-tool standard for a home/global instructions location; the agents.md standard only covers repository-root AGENTS.md. Each tool is wired to the canonical file:

• Factory Droid — reads ~/.agents/AGENTS.md natively (it checks ~/.agents/ as a personal instruction directory).
• Claude Code — ~/.claude/CLAUDE.md imports @~/.agents/AGENTS.md.
• OpenCode — ~/.config/opencode/AGENTS.md is a chezmoi-managed symlink to ~/.agents/AGENTS.md.
• Zed — ~/.config/zed/AGENTS.md is a chezmoi-managed symlink to ~/.agents/AGENTS.md.
• Cursor / Bugbot / Obsidian — no global-file support; use per-repo AGENTS.md / .cursor/BUGBOT.md.

Syncing global rules into a repo

Repo-root AGENTS.md is the only standardized, tool-portable surface, so agents-sync injects the global rules into a repo's AGENTS.md as a managed block (between <!-- BEGIN global agents --> / <!-- END global agents --> markers), preserving repo-specific content:

agents-sync                # inject/refresh into ./AGENTS.md
agents-sync /path/to/repo  # inject into another repo
agents-sync --check        # dry-run: exit 0 if in sync, 1 if stale/missing
agents-sync --remove       # strip the managed block

Re-running agents-sync refreshes the block without duplicating it.

Fonts

Fira Code Nerd Font

brew install font-fira-code-nerd-font

App Preferences

iTerm2

iTerm2 preferences are managed by chezmoi. Enable the iterm2 data flag during chezmoi init to have the preferences plist applied to ~/Library/Preferences/com.googlecode.iterm2.plist.

Rectangle

Rectangle preferences are managed by chezmoi. The preferences plist is applied to ~/Library/Preferences/com.knollsoft.Rectangle.plist on macOS.

Features

Bash version probe

During chezmoi init, chezmoi will probe the current bash found in PATH and persist its major version as data.bashMajor (or 0 if bash is N/A).

Use this data field to help determine whether to deploy a dotfile that requires bash 4.0+ features (e.g. associative arrays) or to deploy one that is portable.