- MacOS or Ubuntu
- Git
- root access
Walk through to install and configure a new MacOS or Linux box
These scripts are idempotent, meaning they can be run again and won't break anything. So if you encounter an error, please fix, it and re-run the install. Once you have it working, feel free to submit a PR.
Browse to https://brew.sh/ and install brew or
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"Run the eval command to get brew in your path
eval "$(/opt/homebrew/bin/brew shellenv)"It's a bit of chicken and egg problem as the installer WILL install Brew but you want to be already running from iTerm.
brew install iterm2While running iterm do the install script
# Clone this repo into your home directory
cd ~
git clone https://github.com/chrishirsch/dotfiles.git
# Run the install script
cd dotfiles/install
./install.shWhile running install and at iTerm, you SHOULD be asked to run p10k configure. Once here go to iTerm
Some files hold settings for one machine and stay out of this repo. Before running the install script:
- Make sure the machine's site document exists in 1Password (see Site settings). The install script creates
~/.siteand the site's other files from it. - Clone the private Claude config repo, and list it in
CLAUDE_EXTRA_DIRSin the site document (see Claude Code).
During the install script:
- after
brew bundle, the script signs in to 1Password if needed (Touch ID with the app's CLI integration, or your password for an account added withop account add), then asks which site document to use - the macOS step shows hidden files in Finder, makes held keys repeat, rebuilds the Dock, and sets the system keyboard shortcuts
- asks whether to use AeroSpace. With AeroSpace, workspaces 1-9 are on Cmd-1..9 and the config is
aerospace/aerospace.toml. Without it, the script waits while you add 9 desktops in Mission Control, sets Cmd-1..9 to switch between them, and stages the Rectangle config for import.
Log out and back in afterwards so every setting takes effect.
- Run p10k configure (if not already prompted)
- Select Install fonts
- Quit all of iTerm as requested
- Restart iTerm and if things don't quite look right, re-run the install.sh and/or p10k configure
Make SURE that you're running iTerm2 when attempting to configure zsh and p10k otherwise nothing works!
If you see
zsh compinit: insecure directories, run compaudit for list. Ignore insecure directories and continue [y] or abort compinit [n]?
You will need to run compaudit and note that there is a directory with incorrect permissions. Fix this by:
compaudit | xargs chmod g-wand validate its working again by opening a new iTerm with no errors.
The macOS step of the install script turns off press-and-hold accents (ApplePressAndHoldEnabled) in macos/defaults.sh, so held keys repeat in vi mode.
Add the Settings Sync plugin by Shan Khan and then login to Git. Select the Gist and then do Shift+Option+D (or Shift+Alt+D) to download and sync
Ensure that
Select Command "Sync : Advanced Options > Toggle Auto-Upload on Settings Change" command to Turn ON
is ENABLED by Shift+Cmd+P and then Sync: Advanced Options > Toggle Auto-Upload on Settings Change (You may have to toggle it depending on it's current default but definitely make sure it's ON)
Unfortunately the Settings Sync that worked perfect with Git and Gists and was private is no longer. So now we get to expose everything to MS to sync. Progress!
To enable the built in Settings Sync, click on the Gear in the lower left, Backup and Sync Settings, Sign in to GitHub (if this is personal or you wish to sync to a SPECIFIC GitHub, make sure you're logged in there first. It won't ask for credentials). You can also sync from your personal settings by signing into the personal, get everything synced, sign out and then sign in with your other account and sync there. Obviously that's a one-shot but at least you get all your plugins, etc.
For the most part, git should be setup and ready to go from the installer. There will probably be site specific settings (ie your git email for the company you are developing for may be different). If so, just create a ~/.gitconfig.user file
[user]
name = Chris Hirsch
email = chris.hirsch@somerandomcompany.com
[credential]
helper = cache --timeout 2592000
helper =
helper = /usr/local/share/gcm-core/git-credential-manager
guiPrompt = false
[commit]
gpgSign = true
[credential "https://dev.azure.com"]
useHttpPath = trueThis will override any more general config in ~/.gitconfig
bin/pr-state-record and bin/pr-status keep track of the pull requests you open, grouped by ticket.
pr-state-record <pr-url> [--ticket ABC-1234] [--title "Ticket title"] [--desc "Row description"]records a PR in~/.local/state/pr/<TICKET>.md, one file per ticket and one table row per PR. Re-running it for the same PR updates the row.pr-statusshows the review and merge status of every open PR, from one GitHub GraphQL query. Open PRs carry badges for draft, merge conflicts, behind base, CI failing or pending, and unresolved review threads.--commentslists each unresolved thread under its PR.pr-status --allincludes merged and closed PRs, and--since YYYY-MM-DDincludes those merged or closed on or after the date.--markdownprints "Merged / closed" and "Open" sections without colors, with the unresolved threads, for pasting into notes such as a standup; ticket keys matchingPR_TICKET_PATTERNbecome Obsidian[[wikilinks]]. Each run refreshes the state files and moves a ticket's file to~/.local/state/pr/archive/once all its PRs are merged or closed and the newest one closed more thanPR_EXPIRE_DAYS(default 14) days ago.
The ticket settings live in ~/.site (see Site settings). Without PR_TICKET_PATTERN, PRs go to the housekeeping ticket unless you pass --ticket.
The claude_config step of the install script sets up ~/.claude:
~/.claude/CLAUDE.mdis a local file on each machine. The installer adds an import of the shared rules inai/claude/CLAUDE.md, plus one import for each private repo. Notes for one machine only can go directly in this file.- Each skill in
ai/skills/is linked into~/.claude/skills/, alongside any skills already there. - Private config (the Obsidian vault map, company-specific workflows, private skills) lives in a private repo such as
ai-private. List its path inCLAUDE_EXTRA_DIRS; the installer imports the repo'sclaude/CLAUDE.mdand links itsskills/,commands/, andagents/. It warns whenCLAUDE_EXTRA_DIRSis unset; set it to""on a machine without private config. - The shared rules keep project plans, notes, and proofs in the Obsidian vault at
$OBSIDIAN_VAULT, and working files in atmp/folder at the project root, whichgit/gitignore_globalignores in every repo.
zshrc sources ~/.site for settings that differ between machines:
export PR_TICKET_PATTERN='ABC-[0-9]+' # ticket keys to detect in branch, title, and body
export PR_JIRA_URL='https://example.atlassian.net' # adds a Jira link to each ticket file
export OBSIDIAN_VAULT="$HOME/obsidian/Second Brain" # Obsidian vault for Claude project notes
export CLAUDE_EXTRA_DIRS="$HOME/src/github/ai-private" # space-separated private Claude config repos
export SITE_FILES="acme_npmrc:~/.npmrc" # other files to create from 1Password, see belowEach kind of machine has a site document in the Clients vault of 1Password, named owner first: chris_site_macbook, chris_site_framework, acme_site. Secrets are separate 1Password items named the same way (acme_jfrog), and documents refer to them with secret references instead of holding the values:
export GOPROXY="https://user:{{ op://Clients/acme_jfrog/credential }}@acme.jfrog.io/artifactory/api/go/go,direct"To get a reference, open the item in the 1Password app and choose Copy Secret Reference from the field's menu.
The site_settings step of the install script:
- Creates
~/.sitefrom the site document you choose (defaultchris_site_macbook), with each secret reference replaced by its value. - Creates each file in the site's
SITE_FILESthe same way. Entries aredocument:path, separated by spaces, so document names can't contain spaces.
It never overwrites an existing file; it warns and skips it. To refresh a file from 1Password, move it aside and re-run the script. Files are created with mode 600. If op can't reach the vault or a reference doesn't resolve, the script stops; fix the problem and re-run it. SITE_OP_VAULT and SITE_OP_DOCUMENT override the vault and the default document.
To create a document from a local file, replace its secrets with references, then:
op document create ~/site.tpl --title acme_site --vault Clients
op document get acme_site --vault Clients | op inject > /dev/null && echo ok # check the references resolve
command rm ~/site.tplTo change one: op document get acme_site --vault Clients > ~/site.tpl, edit the file, run op document edit acme_site ~/site.tpl --vault Clients, and delete the local copy.