Dotfiles Public Scripts

Before You Clone And Read Further

• There is a 99% chance a better open-source solution already exists.
• This is a very specific nerd thing and you probably do not need it.
• This may not work for you or your machine. It is highly personal and probably too hardcoded.
• This may not support backup for what you need, but you have a template. Figure it out and submit a PR if you really need it.

This repository is a public scripts and agent-instructions shell of my private macOS dotfiles repo. Things are auto-backed up when I update scripts or their safety rules, so be careful.

The scripts are personal and opinionated, but they can be useful as a reference or as a starting point for your own macOS dotfiles workflow. Read before running.

Current Status

• Backup scripts are the actively used path and are tested on my personal machine.
• Install/restore scripts exist, but they have not been tested on a new machine.
• The private configuration files these scripts normally manage are not included here.
• Some scripts assume specific macOS app locations and command-line tools.
• The shell module is for Zsh and Oh My Zsh. Other shells need their own module.

Requirements

Required for the full workflow:

• macOS
• Bash
• Git
• Xcode Command Line Tools
• Homebrew

Optional tools used by specific modules:

• gh for GitHub PR automation
• terminal-notifier for clickable macOS notifications
• jq, python3, and rsync for config processing/syncing
• mas for Mac App Store app management through Homebrew Bundle
• claude plus an active Claude subscription/login for the default local PR review in the private auto-backup flow
• codex or agy for opt-in local PR review backends
• code, cursor, and app-specific CLIs for editor backups
• npm, pnpm, pip, and related language tools for package backups

How It Works

• backup.sh runs module backup scripts and copies current machine/app state into the private repo.
• install.sh runs module install scripts and applies repo state back to a machine.
• auto-backup/run-backup.sh launches the auto-backup flow.
• auto-backup/auto-commit.sh backs up, commits to a device branch, and can open, review, and merge a PR in the private repo.

Auto-backup flags:

• no flag: use required auto-backup/config.local.toml
• --main-pc: backup, create/reuse PR, run AI review, and squash-merge if approved
• --pr-only: backup, create/reuse PR, and run review without merging
• --test: push/review the current branch without backup or merge
• --no-rebase: skip rebasing on main
• --no-review: skip AI review

The review/auto-merge path runs gh pr diff, pipes that diff into the configured reviewer CLIs in order, then writes the review into the PR description. Those CLIs must already be installed and authenticated because the script runs unattended from Shortcuts or LaunchAgent and cannot complete login prompts. Claude, Codex, AGY, and OpenCode CLI are tested adapters. OpenCode Go direct API is offline-tested and validated against the selected account during setup; Cursor and Ollama are experimental selectors that fail closed. OpenCode CLI runs under its read-only plan agent so an unattended review cannot edit the repo. The separate Go API adapter uses a Zen API key and documented HTTPS inference endpoints. If no configured reviewer can produce a usable review, the PR stays open for manual review.

The shared auto-backup review policy lives in .github/review-prompt.md. Repository instructions in AGENTS.md, its CLAUDE.md compatibility symlink, and .github/instructions/ give CLI agents and GitHub Copilot the same safety boundaries when reviewing public-fork changes.

The repository audit command lives in .claude/commands/audit.md, with .agents/commands/audit.md as a compatibility symlink for agent UIs that discover commands there. It inventories apps, configurations, packages, extensions, and services that the current checkout does not yet track.

Auto-Backup Setup

There are three ways to use auto-backup.

Manual run:

./auto-backup/run-backup.sh

First generate the required ignored machine configuration:

./auto-backup/configure.sh

Install the LaunchAgent if you want a background schedule:

./auto-backup/install.sh

This writes ~/Library/LaunchAgents/com.dotfiles.autocommit.plist and runs every two days by default. Remove it with:

./auto-backup/uninstall.sh

Use Apple Shortcuts if you want a visible macOS automation instead:

./auto-backup/install-shortcut.sh

The setup command launches a dependency-free Python terminal wizard. It queries the models currently available to each selected CLI, shows selection and fallback order on one screen, and saves those IDs for deterministic unattended runs. Up/Down navigates, Space toggles, Left/Right changes priority, Esc goes back, and Q cancels without saving. AGY, OpenCode, and Codex expose model catalogs; Claude Code uses stable aliases and manual entry because it has no machine-readable model-list command. The separate OpenCode Go direct API fetches its current model catalog from the documented models endpoint.

OpenCode CLI reuses its own provider login. OpenCode Go direct API instead prefers OPENCODE_GO_API_KEY from the environment or stores it in ignored auto-backup/.env. That file must have mode 0600, meaning only its owner can read or write it. Setup and LaunchAgent installation validate an existing key and skip the prompt when it works. The Go terms use broad language against programmatic output extraction despite documenting agent API access; use this only for your own internal reviews. Check model privacy terms too—Muse Spark Contributor allows training on prompts and outputs. Failed credential checks offer retry, removal of the Go reviewer, return to model selection, or complete cancellation; HTTP 403 is reported as a possible account, subscription, region, or edge restriction rather than an invalid key.

For non-interactive runners like LaunchAgent or Shortcuts, set at least DOTFILES_REPO_DIR explicitly if the repo is not in the expected location:

export DOTFILES_REPO_DIR="$HOME/Developer/dotfiles"

For PR review/merge modes, authenticate first:

gh auth login
claude        # if using Claude
codex login   # if using Codex
agy           # if using Google Antigravity CLI
opencode      # if using OpenCode CLI
# OpenCode Go direct API key is handled by configure.sh

The script creates a device branch like device/{model}-{serial-suffix}/{username}, pushes the backup commit there, creates or reuses a PR to main, asks the configured reviewer chain to review the diff, and squash-merges only when the review starts with APPROVED.

Modules are organized by area:

• apps/: Homebrew apps and selected app config backup scripts
• cli/: shell, Git, SSH, and miscellaneous CLI setup scripts
• languages/: Node and Python setup/package backup scripts
• macos/: macOS defaults automation
• fonts/: Homebrew-managed font casks plus a user-backed fonts/user/ directory for fonts without a cask equivalent
• history/: shell history backup script
• auto-backup/: scheduled backup and PR automation

What Gets Backed Up Privately

The private repo can store local snapshots for Homebrew apps, shell files/history, Git and SSH config, editor settings/extensions/profiles, AI tool settings, terminal config, app config, Node/Python globals, and macOS defaults.

Those snapshots are intentionally excluded from this public mirror.

Runtime Environment

The scripts can run with defaults, but these environment variables make the setup explicit:

export DOTFILES_REPO_DIR="$HOME/Developer/dotfiles"
export DOTFILES_GITHUB_REPO="your-user/your-private-dotfiles"
export DOTFILES_LOG_DIR="$HOME/Library/Logs/dotfiles"
export DOTFILES_AUTOBACKUP_LOCKFILE="/tmp/dotfiles-autocommit.lock"

DOTFILES_REPO_DIR defaults to the Git root or script location. DOTFILES_GITHUB_REPO defaults to the origin remote slug when it can be parsed.

LaunchAgent and Apple Shortcuts run in a non-interactive environment. If you use them, set required environment variables inside the launcher or load them explicitly.

Auto-backup behavior is configured in ignored auto-backup/config.local.toml. The public mirror ships auto-backup/config.example.toml, but setup must generate the machine-local file before runtime or LaunchAgent installation proceeds.

Safety Notes

• Do not make a full private dotfiles repo public without filtering files and history.
• Review install scripts before running them; they may overwrite local config.
• Keep secrets, SSH config, tokens, app exports, and shell history private.
• Treat this repo as reference code unless you have adapted it to your machine.

License And Small Fee

There is a small fee for using this content: donate to Come Back Alive. Donate anything. As Max Shcherbyna said: "Donate is like a penis, there isn't small one."

This project is licensed under the MIT License - see the LICENSE file for details. Just don't be cunts, and do not support Russia's war against Ukraine.