Personal macOS dotfiles for an Apple Silicon machine, managed with GNU Stow.

Durable architecture and decision records are indexed in docs/index.md.

Install the declared tools, then deploy every package:

brew bundle
./stow_all.sh

The managed packages are bat, fzf, ghostty, git, herdr, lazygit, ripgrep, starship, tmux, and zsh.

Herdr is the primary persistent terminal workspace manager. The existing tmux package remains available as a fallback, but tmux itself is not declared in the Brewfile.

Ghostty uses the licensed MonoLisaCode family for terminal cells and MonoLisaText for window and tab titles. Symbols Nerd Font Mono, installed through the declared Homebrew cask, is the fallback for semantic prompt and UI icons that MonoLisa does not provide. After a macOS light/dark appearance change, Zsh automatically reloads Ghostty at its every-third-prompt appearance check. Idle terminals and active editors wait for that check. If CoreText does not refresh the grade in an existing surface, open a new surface or restart Ghostty. Font files are installed locally and are not part of this repository.

To deploy an individual package other than herdr or zsh, run:

stow --target "$HOME" --restow <package>

For Herdr and Zsh, keep runtime and local files outside the repository by disabling directory folding:

stow --target "$HOME" --restow --no-folding herdr
stow --target "$HOME" --restow --no-folding zsh

Use ./stow_all.sh when migrating an older folded Zsh deployment; it preserves and moves existing local state before restowing. After deploying Herdr, open a new interactive Zsh shell to generate its active configuration.

Generate Starship configurations first when deploying starship alone:

sh starship/.config/src/generate.sh

Delta remains the normal Git pager and interactive staging filter. Interactive Zsh enables these optional commands when difft is on PATH at startup:

git difft                         # Working tree diff
git dshow HEAD                    # Commit with structural diff
git dlog -5                       # History with structural patches
git difftool -t difftastic        # Explicit difftool selection

Open a new shell after installing or removing difftastic. The optional include is inherited by child processes; a nested Zsh removes it if difft is absent. Difftastic uses its native adaptive side-by-side layout, syntax highlighting, three context lines, and automatic terminal width. The commands use less -FRX to preserve colors, exit for short output, and leave the result visible. Automatic color detection keeps redirected output plain. Ghostty's existing Token ANSI palette supplies terminal colors; no extra theme export is needed.

On macOS, Zsh sets DFT_BACKGROUND at startup and updates it at the next scheduled appearance check, every third prompt. Changes affect subsequent difftastic invocations; idle shells wait until another prompt. Override display options for individual commands as needed:

DFT_DISPLAY=inline git difft
DFT_DISPLAY=side-by-side-show-both DFT_CONTEXT=5 git dshow HEAD
DFT_WIDTH=120 DFT_BACKGROUND=light git difft

Mergiraf handles Git merges for all files and detects supported languages automatically. Other text files use ordinary text merging. If mergiraf is missing from PATH, the driver uses git merge-file with the configured conflict style, labels, and marker size. Conflicts and errors from an available Mergiraf are returned directly. Without Mergiraf, binary conflicts retain the current branch's version and remain unresolved for manual resolution; other merge errors still fail.

Herdr starts with its sidebar hidden; Ctrl-B, then B toggles it. The sidebar uses attention-priority agent ordering and status symbols. Panes have outer frames with agent labels and Herdr's built-in gaps between them. A single pane is also framed. The bottom tab bar is hidden for a single tab. Expanded sidebar rows use bold workspace names and dim secondary details. Ctrl-B retains the standard prefix actions, while Alt plus an arrow focuses an adjacent pane directly. New tabs and workspaces prompt for names. Herdr's worktree creation binding is disabled.

Background-agent notifications use Ghostty's terminal notification support after a one-second delay, without sounds. Experimental pane-history persistence is explicitly disabled because saved terminal output may contain sensitive data. The Codex integration is not installed, so Codex panes do not natively resume their conversations after a full Herdr restart.

~/.config/herdr/config.toml is generated from the tracked config.base.toml and selected Token fragment because Herdr does not support configuration includes. Zsh only replaces files carrying its generated header, writes the result privately, and reloads a running default Herdr server after the content changes. Settings UI edits to this generated file are temporary; durable preferences belong in the tracked base and durable colors belong in Token. After editing config.base.toml or synchronizing themes, open a new interactive Zsh shell to regenerate the active configuration.

Token is the color source of truth. Classic Token, Token Flint, Token Temper, Token Ultra, and Token Meridian are all available. Shell tools and Ghostty follow the macOS light or dark mode. Herdr follows the appearance reported by Ghostty and uses both modes from the selected family fragment. Tmux defaults to dark; use its prefix followed by T to toggle light/dark mode. Classic Token is used until another appearance is selected:

token-theme token
token-theme token-flint
token-theme token-temper
token-theme token-ultra
token-theme token-meridian

Run token-theme without an argument to print the current appearance, or use token-theme next to cycle through all five. The selection is stored under ${XDG_STATE_HOME:-$HOME/.local/state} rather than in Git. Existing shells update at their next appearance check, Herdr replaces its active family fragment, tmux reloads the selected family while retaining its light/dark mode, and Ghostty automatically reloads when its adapter changes, including immediately after a token-theme family change.

After Token contrib files are regenerated, sync all five appearances into this repository without modifying Token:

./sync_token_themes.sh /Users/thorre/github/token

The sync script also regenerates the ten ignored family/mode Starship configs and the ignored unthemed fallback from tracked source files.