macsetup

macOS developer environment CLI. Create, configure, and snapshot reproducible setups.

• One command configures a fresh Mac from scratch
• Daily snapshots auto-commit tool versions and configs to GitHub
• Restore your environment on a new Mac in minutes
• AI agent ready — all commands support non-interactive mode

Install

# Prerequisites: Xcode CLI Tools + Homebrew
xcode-select --install
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install macsetup
brew install mise
mise use -g node@lts
npm install -g pnpm
pnpm install -g macsetup

On install, agent skill files are automatically written to ~/.claude/skills/ and ~/.cursor/skills/ so AI coding agents discover macsetup immediately.

Updating

macsetup update

Quick Start

New Mac (interactive)

macsetup init      # Wizard: scan current machine or pick a preset
macsetup setup     # Harden + install tools + configure + snapshot

By default, init scans your machine and generates configs from what's already installed — no preset required. Use macsetup manage anytime to add or remove dependencies interactively.

New Mac (non-interactive / AI agent)

macsetup init --name "Jane Doe" --email [email protected] \
  --github janedoe --repo my-setup --preset recommended --yes

macsetup setup --no-harden --yes

Restore Existing Setup

macsetup restore --github janedoe --repo my-setup --yes
macsetup setup --yes

Commands

| Command | Purpose | |---------|---------| | macsetup init | Create a new workspace with starter configs | | macsetup restore | Clone an existing workspace to a new Mac | | macsetup setup | Full setup: harden + install + configure + snapshot | | macsetup install | Install Homebrew packages, mise runtimes, shell plugins, Docker models | | macsetup configure | SSH keys, git signing, shell config, editor symlinks, GitHub auth | | macsetup snapshot | Capture machine state, detect drift, auto-commit and push | | macsetup doctor | Run health checks (symlinks, packages, runtimes, SSH, LaunchAgent, git) | | macsetup info | Show CLI version, workspace, identity, LaunchAgent, and snapshot status | | macsetup update | Update macsetup CLI to latest version | | macsetup manage | Interactive dependency manager — browse and toggle deps and configs | | macsetup ui | Open web dashboard in browser — manage dependencies, configs, and AI rules/skills for Cursor and Claude (loopback-only, session-token protected) | | macsetup harden | Apply macOS security hardening (FileVault, firewall, screen lock) | | macsetup migrate | Upgrade from legacy two-repo architecture | | macsetup generate-context | Regenerate AI context files from workspace configs | | macsetup version | Show installed version |

Flags

| Flag | Commands | Purpose | |------|----------|---------| | --yes, -y | all | Auto-confirm all prompts (non-interactive mode) | | --name <n> | init | Full name for git config | | --email <e> | init | Email for git config | | --github <u> | init, restore | GitHub username | | --repo <r> | init, restore | Repository name (default: setup-snapshots) | | --location <p> | init, restore, migrate | Workspace directory path | | --preset <id> | init | Config preset: minimal, recommended, full | | --no-harden | setup | Skip macOS security hardening phase | | --dry-run | setup | Run doctor checks without making changes |

Config Presets

When running macsetup init, choose a preset that matches your needs:

| Preset | What's Included | |--------|----------------| | minimal | Shell config (.zshrc), git config (.gitconfig.template), Brewfile, mise runtimes | | recommended | Minimal + starship prompt, ghostty terminal config, topgrade updater, editor settings | | full | Recommended + LLM models, coding conventions, Claude & Cursor settings |

Presets are starter configs copied into your workspace. You own them after init — customize freely.

How It Works

Workspace

macsetup manages a workspace — a private GitHub repo on your machine containing your configs, snapshots, and identity:

~/dev/setup-snapshots/             # Your workspace
├── identity.yml                # Name, email, GitHub user, repo name
├── preferences.yml             # Opt-in list of configs macsetup manages
├── configs/                    # Your dotfiles (source of truth)
│   ├── .zshrc                  # Shell aliases, PATH, plugins
│   ├── .gitconfig.template     # Git config with {{NAME}}, {{EMAIL}} placeholders
│   ├── Brewfile                # Homebrew packages and casks
│   ├── mise-config.toml        # Language runtimes (Node, Python, etc.)
│   ├── starship.toml           # Shell prompt config
│   ├── ghostty-config          # Terminal config
│   ├── topgrade.toml           # System updater config
│   ├── cursor-settings.json    # Editor settings (symlinked live)
│   ├── claude-settings.json    # Claude Code settings (symlinked live)
│   ├── ai/                     # Versioned AI config: Cursor/Claude rules, skills, agents + cursor-user-rules.md
│   └── ...
└── snapshots/                  # Auto-generated machine state
    ├── brew-versions.txt       # Every formula with exact version
    ├── brew-cask-versions.txt  # Every GUI app with exact version
    ├── mise-versions.json      # Runtime versions
    ├── system-info.txt         # Chip, RAM, hostname
    ├── macos-security.txt      # FileVault, SIP, Gatekeeper status
    └── ...

Workspace location is stored in ~/.config/macsetup/config.yml.

Identity

identity.yml in your workspace personalizes everything:

name: Jane Doe
email: [email protected]
githubUser: janedoe
repoName: setup-snapshots
launchAgentLabel: com.janedoe.macsetup.snapshot

Config files with the template flag (like .gitconfig.template) use {{NAME}}, {{EMAIL}}, {{GITHUB_USER}} placeholders that are rendered from your identity on install.

What Each Phase Does

macsetup harden — macOS security hardening:

• FileVault full-disk encryption
• Firewall with stealth mode, auto-allow disabled
• Screen lock requires password immediately
• Remote login, screen sharing, and file sharing disabled
• Secure Finder defaults (show hidden files, extensions, path bar)
• Safari auto-open downloads disabled
• Automatic critical security updates
• Developer-friendly key repeat speed
• Prints a manual checklist for System Settings items that require the GUI

macsetup install — Tool installation:

• Homebrew formulas and casks from your Brewfile
• Language runtimes via mise from mise-config.toml
• Shell plugins (Zinit, autosuggestions, syntax highlighting)
• Docker Model Runner models from llm-models.txt (if present)
• Claude Code (if not already installed)

macsetup configure — Environment configuration:

• Reads preferences.yml to determine which configs to deploy (safe opt-in model)
• Generates SSH ed25519 keys (authentication + signing)
• Configures SSH for GitHub
• Creates git allowed signers file for commit verification
• Renders and installs only opted-in templated configs (git, shell)
• Copies only opted-in managed configs to live locations
• Symlinks only opted-in editor settings (Cursor, Claude Code)
• Authenticates GitHub CLI
• Displays SSH public keys for GitHub registration

macsetup snapshot — State capture:

• Records Homebrew formula and cask versions
• Captures mise runtime versions
• Backs up active config files
• Captures global AI config (Cursor rules/skills, Claude skills/agents/commands/hooks) into configs/ai/ and exports Cursor User Rules
• Regenerates AI grounding files (~/.claude/CLAUDE.md, ~/.cursor/rules/dev-environment.mdc) from workspace config sources so agent context never goes stale
• Records macOS version, security state, system info
• Detects config drift (live files vs workspace source), including AI config dirs
• Auto-commits changes with descriptive messages
• Pushes to GitHub
• Sends macOS notifications on drift detection or push failures
• Writes heartbeat file for staleness monitoring

macsetup doctor — Health checks:

• Workspace exists and is accessible
• Identity file present
• Config symlinks intact (editor settings)
• Managed config files installed
• Homebrew packages present
• Mise runtimes installed
• SSH keys exist
• LaunchAgent loaded
• Git hooks installed (Lefthook)
• Heartbeat freshness (snapshot ran within 36 hours)
• Workspace and setup repo git status

Daily Snapshots

A LaunchAgent runs macsetup snapshot daily at 10:00 AM and on login. Changes auto-commit to your workspace repo with descriptive messages and push to GitHub. If config drift is detected (live files differ from your workspace source), a macOS notification alerts you.

Before each push, the snapshot scans staged files for secrets (API keys, tokens, private keys) and refuses to commit or push if any are found — or if your snapshot repo is public — to keep your dotfiles safe. The LaunchAgent plist is written with restrictive permissions and macsetup doctor verifies its integrity.

AI Agent Integration

macsetup is designed for both humans and AI agents:

• On install: Agent skill files (SKILL.md) are written to ~/.claude/skills/ and ~/.cursor/skills/ via postinstall hook — agents discover macsetup immediately
• On configure: Full environment context (tools, runtimes, aliases, conventions) is written to ~/.claude/CLAUDE.md and ~/.cursor/rules/dev-environment.mdc; opted-in AI config dirs are deployed from configs/ai/
• On generate-context: Regenerates AI context files from workspace config sources (also runs automatically via pre-commit hooks when configs change). Hand edits between the macsetup:user-start/macsetup:user-end markers are preserved across regeneration
• Round-trip AI config: Global Cursor rules/skills and Claude skills/agents/commands/hooks are versioned in configs/ai/, imported on init/snapshot and deployed on configure (opt-in per directory). Sensitive filenames (keys, .env, .npmrc, .netrc, credentials) are excluded, and the content secret-scanner blocks any embedded credential before push
• Cursor User Rules: Since Cursor stores User Rules in the cloud (no local file), the macsetup ui dashboard versions them in configs/ai/cursor-user-rules.md — edit, copy, paste into Cursor Settings → Rules → User Rules, then mark applied. A per-machine hash flags them "needs apply" whenever the versioned rules change
• All commands: Support --yes flag for zero-prompt execution
• All identity fields: Accepted as CLI flags (--name, --email, --github)

Follows the npm-agentskills convention.

Requirements

• macOS (Apple Silicon or Intel)
• Node.js >= 20.0.0
• Xcode Command Line Tools
• Homebrew

License

SEE LICENSE IN LICENSE — Copyright (c) 2026 Mike Mikula. All rights reserved.