Your agentic engineering system, explained.

01 / System map

The mental model

The setup is not one tool. It is a set of layers with clear ownership. Most confusion disappears once you know which layer owns a change.

Why the symlinks matter

Home Manager creates managed paths such as ~/.config/wezterm, but they ultimately point into ~/dotfiles through the stable ~/.dotfiles link. An application reads its normal home-directory path while Git records the real file in the repository.

02 / Daily loop

The safe change cycle

Use this loop for almost every configuration change. It keeps each decision visible and gives Git a clean recovery point.

cd "$HOME/dotfiles"
git status --short

micro configuration.nix

git diff --check
git --no-pager diff -- configuration.nix

./rebuild.sh

git add configuration.nix
git commit -m "Describe the behavior changed"
git push origin main
git status --short

nix flake check --no-build
nix build .#darwinConfigurations.mac.system --dry-run

03 / What to edit

Does this need a rebuild?

The answer depends on whether Nix generates the result or an application reads a linked file directly.

04 / Install software

Put software in the right list

Use Nix for ordinary command-line tools when they exist in nixpkgs. Use Homebrew casks for macOS applications. Keep Homebrew formulae for tools that are Homebrew-specific or integrate better there.

home.packages = with pkgs; [
  bat
  fd
  fzf
  git
  hermes-agent.packages.${pkgs.stdenv.hostPlatform.system}.default
  htop
  jq
  lazygit
  micro
  opencode
  ripgrep
  rsync
  shellcheck
  tmux
  tree
  treehouse.packages.${pkgs.stdenv.hostPlatform.system}.default
  typescript
  uv
  wget
  cowsay  # example new package
  nerd-fonts.hack
];

taps = [
  { name = "automic-vault/isotopes"; trusted = true; }
  { name = "my-monkeys/tap";         trusted = true; }
];

brews = [
  "herdr"
  "example-formula"
];

casks = [
  "wezterm"
  "claude-code"
  "codex"
  "my-monkeys/tap/opensuperwhisper"
  "example-app"
];

Apply and verify

cd "$HOME/dotfiles"
git diff --check
git --no-pager diff
./rebuild.sh
rehash
command -v NAME || echo "NAME is missing"

Removing software

Delete the declaration, rebuild, verify, and commit. Nix packages disappear from the active user profile. Homebrew items are removed on the next rebuild, because the cleanup policy is set to uninstall.

The container layer

OrbStack is the container and Linux VM runtime, not Docker Desktop. The docker formula is only the CLI client; the daemon it talks to comes from OrbStack, which registers an orbstack Docker context and makes it current on first launch. The Homebrew client ships no subcommand plugins, so home.nix links ~/.docker/cli-plugins/docker-compose and docker-buildx straight at the binaries inside OrbStack.app. That keeps docker compose working without OrbStack's GUI onboarding step, which is what would otherwise create ~/.orbstack/bin and never runs on a headless setup.

The npm layer (not managed by Nix)

home.nix sets NPM_CONFIG_PREFIX to ~/.npm-global and puts its bin on the PATH, so npm globals land in a writable prefix rather than alongside the runtime. First Mate's worker CLIs are installed there imperatively: gh-axi, chrome-devtools-axi, lavish-axi, tasks-axi, quota-axi, and gnhf. The no-mistakes validation pipeline lives at ~/.no-mistakes/bin (also on the PATH from home.nix); point NO_MISTAKES_LINK_DIR at that same directory when installing so it skips the one step that wants sudo. On a fresh Mac these need one reinstall pass; the README's "Agent worker tooling" section has the exact commands.

The no-mistakes daemon runs in the foreground from a herdr pane, not from its launchd agent. Start it with the nms alias (~/dotfiles/bin/no-mistakes-daemon) and leave it in its own pane; herdr keeps it across disconnects and restarts, and the nms-autostart herdr plugin recreates that pane after every session restore.

When a rebuild changes the PATH, existing terminal sessions keep the old one: home-manager guards its session variables with __HM_SESS_VARS_SOURCED, and every nested shell inherits the guard, so agents launched from a pre-rebuild shell see command not found for tools that are actually installed. Open a fresh WezTerm tab (or reboot) and restart long-lived hosts like the herdr server from it.

05 / WezTerm + Micro

Your working surface

WezTerm owns the terminal window. Zsh owns the shell inside it. Starship draws the prompt. Micro is the default text editor.

WezTerm settings in plain language

Micro essentials

06 / ripgrep + fzf

Find text, then choose a result

These are two separate tools that become especially useful together. rg, the ripgrep command, searches file contents. fzf gives you an interactive way to narrow and select lines from any list.

Start with ripgrep

cd "$HOME/dotfiles"

rg "home.packages"                 # search every normal text file
rg -n "home.packages" home.nix     # search one file with line numbers
rg -i "wezterm"                    # ignore upper/lower case
rg -F 'a.literal.value'            # treat punctuation literally
rg -g '*.nix' "homebrew"           # search only Nix files
rg -l "claude"                     # print matching filenames only
rg --files                         # list searchable project files

When a search finds nothing

By default, ripgrep skips hidden files, binary files, and ignored paths. Include hidden files while still excluding Git internals with:

rg --hidden -g '!.git' "statusLine" "$HOME/.claude"

Use fzf on its own

cd "$HOME/dotfiles"
rg --files | fzf

The pipe character | sends the file list produced by rg --files into fzf. Choosing a line prints that filename back to the terminal.

Open the selected file in Micro

cd "$HOME/dotfiles"
file="$(rg --files | fzf)"
[ -n "$file" ] && micro "$file"

Search file contents, then choose a matching file

cd "$HOME/dotfiles"
file="$(rg -l "homebrew" | fzf)"
[ -n "$file" ] && micro "$file"

07 / Herdr

Persistent agent workspaces

Herdr sits inside WezTerm and keeps terminal work alive independently of the window. Closing WezTerm does not need to terminate your running agents.

Start, leave, and stop

herdr                 # start or reattach

# Inside Herdr: Ctrl-b, release, then q to detach

herdr server stop     # actually stop the session and its panes

Your configured keys

Two non-key settings also live in home/.config/herdr/config.toml: onboarding = false skips the first-run tour, and agent_panel_sort = "spaces" groups the agents panel by space rather than by priority. Copy mode's own internal keys (v / Space to select, y / Enter to copy, q / Esc to cancel) are fixed by Herdr and not configurable; only the key that enters copy mode is.

The startup plugin

herdr-plugins/nms-autostart is a Herdr startup plugin kept in this repo. Herdr runs it once after it restores a session and its API socket is ready. Session restore brings panes back as empty shells, so the plugin checks whether the no-mistakes daemon is running and, if not, recreates an NMS tab in the dotfiles workspace and starts the blessed launcher in it. That is why the pipeline daemon survives a full restart without you doing anything.

A useful project layout

08 / Agents

Shared rules, different permission models

Claude, Codex, and OpenCode share one global instruction file and one skills directory. Pi and Hermes are separate agents with their own state, and First Mate is a writable agent distro that coordinates crews across registered projects.

One instruction source

# shared policy: one file, three harnesses
~/.claude/CLAUDE.md            -> ~/dotfiles/home/AGENTS.md
~/.codex/AGENTS.md             -> ~/dotfiles/home/AGENTS.md
~/.config/opencode/AGENTS.md   -> ~/dotfiles/home/AGENTS.md

# hand-authored skills: one directory, three roots
~/.agents/skills/bro           -> ~/dotfiles/home/skills/bro
~/.claude/skills/bro           -> ~/dotfiles/home/skills/bro
~/.codex/skills/bro            -> ~/dotfiles/home/skills/bro

# Claude's own configuration
~/.claude/settings.json        -> ~/dotfiles/home/.claude/settings.json

Edit home/AGENTS.md when a preference should apply to Claude, Codex, and OpenCode. Use project-local instruction files when a rule only belongs to one repository. Pi, Hermes, and First Mate maintain their own operational state and instructions.

First Mate project workflow

gh auth login
cd "$HOME/firstmate"
claude

# In chat:
Add https://github.com/OWNER/REPO as a no-mistakes project.
Do not start any work yet.

First Mate keeps its managed clones under ~/firstmate/projects and gives workers isolated worktrees. Use no-mistakes for its full validation and PR pipeline, direct-PR for a faster PR path, or local-only when no remote is required.

Its worker tooling is fully installed on this machine: tmux hosts each worker session, Treehouse provides the isolated worktree pool, tasks-axi is the durable task queue, quota-axi checks usage headroom before dispatch, gh-axi / chrome-devtools-axi / lavish-axi cover GitHub, browser, and report work, and no-mistakes gates deliveries. The lavish and gnhf agent skills are installed globally with the skills CLI; no-mistakes ships its own.

Crewmates launch through bin/fm-claude, a blessed launcher wired in via First Mate's untracked config/claude-launcher. It is a deliberate pure passthrough to claude "$@": First Mate's spawn script owns the flags, the model and effort selection, and the encoded launch brief, so rewriting the arguments here would break its adapter.

The no-mistakes daemon is a single shared instance serving every lane, so restarting it kills other lanes' in-flight pipeline runs. Leave it to First Mate; restart it by hand only when nothing is running.

Pi's selective setup

Home Manager deliberately does not own ~/.pi/agent itself. It links exactly four things - the themes and extensions directories, plus models.json and settings.json as individual files - so Pi's authentication, sessions, trust decisions, caches, and downloaded package trees all stay local and untracked. Run /reload inside Pi after editing a linked file.

The local extensions directory is for repository-authored extensions only; third-party package code never belongs there. Two extensions live there today: a terminal-title extension that shows a spinner while Pi is working, and Pi Calm, a conversation-only presentation mode toggled with /calm and off by default. Calm hides collapsed thinking and the call/result shells for Pi's seven built-in tools, and replaces the working row with an animated widget; it never changes prompts, tool execution, model context, session data, or ordering, and /share and /export still use the complete stock transcript. Its on/off choice is stored locally, not in this repo. tests/pi-calm.test.sh is the shell test suite that proves all of that.

Claude status line and settings

home/.claude/statusline.sh reads the JSON payload Claude pipes to it and renders model | directory | branch | context% | effort | output style. The branch is not in that payload, so the script asks Git for it. This is why jq is part of the Nix user package list.

home/.claude/settings.json also registers three SessionStart hooks - gh-axi, chrome-devtools-axi, and lavish-axi - which print ambient context into each new session, and sets the permission mode, TUI mode, and theme.

Authentication is deliberately not in Git

OAuth sessions, tokens, keychain entries, auth.json, histories, logs, and local plugin cache state should remain local. Configuration is reproducible; credentials must be restored interactively.

09 / Git + Lazygit

Maintain the source of truth

Git records each proven setup change. Lazygit is a visual terminal interface for reviewing and operating that same Git repository. GitHub protects the checkpoints from loss and lets the fork receive upstream improvements.

What Lazygit is showing you

Your first Lazygit session

cd "$HOME/dotfiles"
lazygit

Lazygit action to Git command

Normal maintenance

cd "$HOME/dotfiles"
git status --short
git diff --check
git --no-pager diff

git add path/to/changed-file
git commit -m "Describe the behavior changed"
git push origin main
git status --short

Understand the remote

This repository has exactly one remote, and it is an SSH remote on purpose. An HTTPS remote plus the osxkeychain credential helper would let any process on the machine retrieve the GitHub token through git credential fill; an SSH remote is not extractable that way.

There is no upstream. If you forked this repo and want to track it, add one yourself with git remote add upstream https://github.com/MattH-ca/m.dotfiles.git, then compare before merging:

git fetch upstream
git log --oneline --left-right main...upstream/main

Lines beginning with < are unique to your fork. Lines beginning with > are new upstream. Review before merging, because your editor, Dock, packages, and safety choices will intentionally differ. Use a normal merge and resolve conflicts deliberately; avoid git reset --hard and avoid force-pushing a customized main.

Small recoveries

10 / Updates

Update intentionally

Pinned inputs give you repeatability. Updating is a deliberate change that should be reviewed, rebuilt, tested, and committed.

Nix inputs

cd "$HOME/dotfiles"
git status --short
nix flake update
git --no-pager diff -- flake.lock
./rebuild.sh
git add flake.lock
git commit -m "Update Nix flake inputs"
git push origin main

The release branches remain 26.05, while flake.lock advances to newer exact revisions on those branches.

Homebrew-managed software

configuration.nix sets homebrew.onActivation.autoUpdate = true, so each rebuild refreshes Homebrew's formula and cask data on its own. Upgrading the installed packages is still a separate, deliberate step.

brew outdated

# Upgrade a specific declared tool after reviewing the list
brew upgrade herdr
brew upgrade --cask wezterm claude-code codex

Homebrew itself is pinned by Nix

cd "$HOME/dotfiles"
nix flake update nix-homebrew
./rebuild.sh

11 / Recovery

Rebuild the setup on another Mac

The repository reproduces declared configuration. Authentication, private data, and undeclared Homebrew extras remain separate.

cd "$HOME"
git clone https://github.com/MattH-ca/m.dotfiles.git dotfiles
cd "$HOME/dotfiles"
./bootstrap.sh

What is not reproduced automatically

• GitHub, Claude, Codex, Pi, OpenCode, and Hermes login sessions or provider keys
• SSH private keys and Keychain contents, including everything stored in Automic Vault
• The blessings on the bin/ launchers - each one needs av bless again on a new machine
• Repositories other than this one and the fresh First Mate clone, plus First Mate's untracked local config
• The npm-installed worker CLIs (see the README's "Agent worker tooling" section for the reinstall commands)
• Skills installed by the skills CLI - only the hand-authored ones under home/skills/ are in this repo
• The nms-autostart Herdr plugin, which lives here but has to be installed into Herdr
• Pi's downloaded npm and git package trees, and Micro's own ~/.config/micro
• Wallpaper choice and other intentionally manual personal content
• The planned isolated sandbox network

12 / Troubleshooting

Known fixes from this build

These are the failures we actually encountered and the reasoning behind each fix.

source /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
exec zsh -l
nix --version

cd "$HOME/dotfiles"
./rebuild.sh

ls -l /opt/homebrew/share/zsh/site-functions/_brew
test -L /opt/homebrew/share/zsh/site-functions/_brew && \
  rm /opt/homebrew/share/zsh/site-functions/_brew
find "$HOME" -maxdepth 1 -name '.zcompdump*' -delete
exec zsh -l

printf 'Menu bar autohide: '
defaults read NSGlobalDomain _HIHideMenuBar

printf 'Dock autohide: '
defaults read com.apple.dock autohide

printf '%s\n' "$PATH" | tr ':' '\n'
command -v THE_MISSING_TOOL

cd "$HOME/dotfiles"
nix flake update nix-homebrew
./rebuild.sh

13 / Audit

Run a system check

This audit is read-only. It checks repository cleanliness, important command paths, macOS behavior, managed links, GitHub authentication, and services.

cd "$HOME/dotfiles"

printf 'Repository: '
test -z "$(git status --porcelain)" && echo CLEAN || git status --short

printf 'Menu bar autohide: '
defaults read NSGlobalDomain _HIHideMenuBar

printf 'Dock autohide: '
defaults read com.apple.dock autohide

for cmd in nix brew darwin-rebuild micro node fzf jq rg lazygit gh herdr hermes \
           claude codex opencode pi wezterm av treehouse tmux uv shellcheck \
           tsc docker no-mistakes
do
  printf '%-16s %s\n' "$cmd" "$(command -v "$cmd" || echo MISSING)"
done

printf '\nManaged instruction links:\n'
ls -l "$HOME/.claude/CLAUDE.md" "$HOME/.codex/AGENTS.md" "$HOME/.config/opencode/AGENTS.md"

printf '\nManaged skill links:\n'
ls -l "$HOME/.agents/skills/bro" "$HOME/.claude/skills/bro" "$HOME/.codex/skills/bro"

printf '\nManaged Pi links:\n'
ls -l "$HOME/.pi/agent/themes" "$HOME/.pi/agent/extensions" \
      "$HOME/.pi/agent/models.json" "$HOME/.pi/agent/settings.json"

printf '\nVault health:\n'
av doctor

printf '\nLauncher keys in the vault:\n'
grep -ho '+[A-Z_][A-Z0-9_]*' "$HOME"/dotfiles/bin/* | tr -d '+' | sort -u |
while read -r k; do
  printf '%-24s ' "$k"
  av list | grep -qx "$k" && echo present || echo MISSING
done

printf '\nFirst Mate clone:\n'
git -C "$HOME/firstmate" status --short --branch

printf '\nno-mistakes daemon:\n'
no-mistakes daemon status

printf '\nGitHub authentication:\n'
gh auth status

printf '\nHomebrew services:\n'
brew services list

Expected results

14 / Automic Vault

Gate secret access, especially for agents

This is the load-bearing security layer of the whole setup, and the one piece that makes the rest of it safe to run. Everything else here is about giving agents more autonomy; this is the counterweight.

Automic Vault answers that by moving secrets into the macOS Keychain and putting a human-approval gate between your tools and those secrets. It ships in this setup as a Homebrew tap, a hardened gh, and a menu bar app.

How it is wired here

Three declarations install it, plus one PATH entry so the av command resolves. A fresh rebuild.sh brings all of this along, which is why an agent's first gh call can surface an approval prompt.

# configuration.nix - trusted tap, hardened gh, the app
taps  = [ { name = "automic-vault/isotopes"; trusted = true; } ];
brews = [ "automic-vault/isotopes/gh-cli" ];
casks = [ "automic-vault" ];

# home.nix - put the av CLI on PATH
home.sessionPath = [ "/Applications/Automic Vault.app/Contents/MacOS" ];

The blessed launchers in bin/

Four scripts in this repo start a tool with exactly one secret already in its environment. Each has an av inject shebang, so the secret exists only inside that process and never touches disk or a command line.

The whole command surface

av help prints this list; it is short enough to learn in one sitting.

Reading the two audit commands

Hardening a tool

A hardener does more than wrap a binary: it migrates that tool's existing credentials out of its plaintext config and into the Keychain, then leaves a small launcher on PATH in its place. Automic Vault ships around fifty of them, covering the usual credential-bearing CLIs - aws, docker, brew, gh, stripe, supabase, node, sudo and many more. This config declares the hardened GitHub CLI as a Homebrew formula so a rebuild installs it; anything else is an interactive choice.

av hardeners --json | jq -r '.hardeners[]
  | select(.applicable) | "\(.name)\t hardened=\(.hardened)"'

av harden sudo     # e.g. approve sudo with Touch ID instead of a password
av doctor          # confirm it is healthy afterwards

Store and inject your own secrets

Instead of exporting a key in a dotfile or a .env, keep it in the vault and hand it to one command for the duration of that command only.

av save OPENAI_API_KEY                       # prompts for the value; stores it in the Keychain
av inject +OPENAI_API_KEY -- python train.py # the key exists only inside this process

For a script you run often, put av inject in its shebang and av bless the file - the same pattern the bin/ launchers above use.

#!/usr/local/bin/av inject +OPENAI_API_KEY /bin/zsh -f
python eval.py

# then approve the exact file once:
av bless ./run-eval.sh

Standing this up on a new machine

The rebuild installs the tap, the hardened gh, the app, and the PATH entry. Everything after that is deliberately manual, because it is exactly the part that must not be reproducible from a public repository.

for f in cc fm-claude no-mistakes-daemon; do
  av bless "$HOME/dotfiles/bin/$f"
done
av doctor

Keep GitHub tokens out of reach

An HTTPS remote plus the osxkeychain credential helper lets any process retrieve your GitHub token through git credential fill. Prefer SSH remotes, which are not extractable that way.

git remote set-url origin git@github.com:OWNER/REPO.git
printf 'protocol=https\nhost=github.com\n\n' | git credential reject  # drop the cached token

15 / References

Standing on other people's work

Almost nothing here was invented for this repository. It is an assembly of other people's projects, and the parts that feel clever are usually theirs. This section credits what it was built from, then points at the documentation worth reading.

The agent layer

A large share of the orchestration tooling is also Kun Chen's. First Mate coordinates the crews, Treehouse gives each worker an isolated worktree, no-mistakes gates every delivery, and the axi CLIs are what the agents actually reach for.

The tools this setup is made of

Documentation