This repository manages a macOS-first development environment with mise. Shared configuration also supports Ubuntu and Debian-based Linux machines without changing the macOS package and configuration defaults.
The checked-in LazyVim lockfile pins editor plugin versions.
mise.toml contains shared state. Mise automatically adds mise.macos.toml or
mise.linux.toml through the managed global miserc.toml. macOS remains the
primary setup and keeps Homebrew ownership of its packages. The Linux layer uses
apt for system dependencies and mise for versioned command-line tools.
Start with Xcode Command Line Tools, which provide Git and a C compiler:
xcode-select --installThe command opens an Apple installation dialog when the tools are missing. Complete it before continuing.
Install Homebrew with its current official installer:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"Load Homebrew in the current shell, then install mise. Homebrew uses /opt/homebrew on Apple Silicon and /usr/local on Intel Macs:
if [[ -x /opt/homebrew/bin/brew ]]; then
eval "$(/opt/homebrew/bin/brew shellenv)"
else
eval "$(/usr/local/bin/brew shellenv)"
fi
brew install miseMise must exist before this repository can bootstrap the rest of the machine.
GitHub SSH access must also be configured so bootstrap can clone the private
pfleidi/skills repository. Clone this repository and bootstrap from its real
checkout path:
git clone https://github.com/pfleidi/dotfiles.git "$HOME/dotfiles"
cd "$HOME/dotfiles"
MISE_AUTO_ENV=true mise bootstrap --dry-run
MISE_AUTO_ENV=true mise bootstrap --yes
mise bootstrap status
mise run verifyThe $HOME/dotfiles destination is only an example. Dotfile sources are relative to mise.toml, so the checkout can live anywhere.
The first bootstrap installs OrbStack when it is missing. Open the OrbStack app
once afterward to finish its setup.
Review the plan before applying it:
cd <dotfiles-checkout>
MISE_AUTO_ENV=true mise bootstrap --dry-run
MISE_AUTO_ENV=true mise bootstrap --yes
mise bootstrap status
mise run verifyBootstrap is convergent: packages, repositories, and links already in the
declared state are left alone. Mise installs or safely updates clean Oh My Zsh
and private skills checkouts and refuses conflicting or locally modified
checkouts. Oh My Zsh's own updater is disabled so mise remains its only update
path. The final bootstrap task refreshes the local Claude plugin and reapplies
Herdr's Claude and Codex integrations. It never logs either agent in.
Do not use --force-dotfiles. If a destination conflicts, stop and move it under:
~/.local/state/dotfiles-backups/<timestamp>/
Then rerun the dry-run.
Bootstrap installs missing packages; it does not upgrade everything. Updates are explicit:
mise run updateThe task updates managed repositories and declared platform packages, synchronizes LazyVim plugins, runs verification, and leaves every change visible to Git. It never commits or pushes.
The today command runs kanban-md against the same local board from any
working directory. Initialize the board once:
today init --name Today --statuses planned,in-progress,blocked,done --wip-limit in-progress:1The board lives at ~/.local/share/kanban-md/today. Open its live terminal
view or use any regular kanban-md command through the wrapper. This is a
personal action list, not work intake for coding agents:
today tui
today list
today boardRun herdr-agent in the Herdr tab or pane where the agent should work:
herdr-agent
herdr-agent -- 'Review the current changes.'The script lists Codex and Claude Code when their executables are available in
PATH. It waits for an explicit choice without a timeout or default, even when
only one is installed. Blank or invalid input keeps the selector open; q,
Ctrl-C, or end-of-input cancels. A failed launch never switches agents.
The selected CLI starts a fresh interactive session in the same pane and working
directory, with the optional prompt passed unchanged. Herdr detects it normally;
use the pane ID to address it. Login and agent settings remain managed by each
CLI. The script requires a Herdr pane with an interactive terminal and is
available through the managed ~/.bin link.
The public Git config includes this ignored machine-local file:
~/.config/git/config.local
Use config/git/config.local.example as its shape. Identity and signing settings belong in the local file; this repository overrides its author email locally with the personal GitHub address.
zsh/secrets.zsh is ignored and sourced only when present. Claude and Codex
login state, tokens, session databases, private global agent instructions,
skills, and generated Herdr integration files stay outside this repository.
Bootstrap links private instructions and skills without copying their contents
here.
Zsh keeps completion state under ~/.cache/zsh. Ruby version management is not initialized globally; use mise in Ruby projects or opt into rbenv from local shell configuration on machines that need it.
Starship uses the managed ~/.config/starship.toml prompt configuration. Direnv has no global configuration; its official Oh My Zsh plugin provides the shell hook.
After a fresh bootstrap, run claude and codex interactively if either CLI still needs authentication.
Linux bootstrap installs op. Authenticate inside Linux rather than through
1Password for Mac:
op account add
eval "$(op signin)"op account add is only needed the first time.
Generate the private repository manifest from an existing directory of Git working trees:
agentbox sync-repos DIRECTORYThe command searches recursively, stops below each working tree, and writes
only normalized GitHub SSH remotes to ~/.config/agentbox/repos. It rejects
unsupported or credential-bearing remotes and clone-directory collisions. A
failed scan leaves the previous manifest unchanged; the source directory is
not stored.
The versioned config/agentbox/workbox.json template selects the distribution,
architecture, CPU count, memory in MiB, and disk size in GiB. agentbox create
validates the file before touching OrbStack, uses it for new machines, and
reapplies its resource limits to an existing isolated machine without deleting
guest data. A distribution without a version, such as ubuntu, follows
OrbStack's current default release.
Changes are kept in focused Git commits. Revert the unwanted commit, inspect the new plan, and reapply the declared state:
git revert <commit>
mise bootstrap --dry-run
mise bootstrap --yes
mise run verifyMise converges declared links but does not remove a link whose declaration disappeared in a reverted commit. Inspect such a destination before removing or relinking it. Backed-up symlinks can be restored with cp -P from the backup directory.
The bootstrap package list is the minimal development environment. The Brewfile is the complete machine inventory of Homebrew, Go, and npm packages; normal bootstrap does not apply it.
mise run brew-install
mise run brew-dumpbrew-install installs missing Brewfile entries without upgrading installed packages. brew-dump replaces the Brewfile with a snapshot of the current machine. Neither task removes packages.