What is dot

dot sets up a Mac from plain-text config, keeps it that way, and works with you on your projects.

dot is a macOS setup you own as code. You describe the Mac you want in plain text, and one command makes the Mac match it:

dock visibility hidden
trackpad tap-to-click true
brew cask ghostty

dot check compares the Mac with that description and changes nothing. dot apply fixes only what differs, so running it twice is safe. Every line is explained by dot explain, and the whole engine is POSIX shell plus the tools macOS already has.

Two sides

• Your Mac. System preferences, apps, command-line tools, your shell, editor, language versions, git identity and signed commits, all declared in config/. A new Mac is one installer away from yours; an old one drifts back into line with dot apply.
• Your projects. dot stays after setup. dot clone puts every repository at ~/code/<owner>/<repo>, and dot secret keeps a project’s secrets in 1Password, attached by reference and never written to disk.

Yours to fork

The repo holds the engine (src/) and one person’s choices (config/). You fork it, change the choices, and keep everything personal in a single file, dot.toml, that git ignores. Your fork stays yours; pulling improvements from upstream is a normal git merge.

Built for agents too

dot check never changes anything and never needs a password, so an agent can run it freely. Anything that changes the Mac waits for you. The repo carries its own instructions for agents, and these docs ship as llms.txt and raw Markdown.

Where to go next

• Install it on a Mac.
• How dot compares with chezmoi, yadm and classic dotfiles repos.
• How it works, if you want to see the engine first.