Graphical apps
The apps around the terminal — browsers, a launcher, notes.
Not everything happens in a terminal. On a Mac, Groundwork installs a small desktop layer around the agent workflow: the browser you inspect with, a launcher that keeps context one keystroke away, a durable link library, display controls, and notes. Linux/headless profiles skip this layer; the point is to support the work, not make every app mandatory.
What Groundwork can configure
Groundwork should only automate settings that live in stable files, templates, or documented macOS defaults. Many Mac apps keep their real state in app databases, account sync, Keychain, iCloud, or per-device stores; those should stay in the app that owns them.
| Managed by Groundwork | Shell, Git, tmux, Neovim, Ghostty, Karabiner merge config, selected macOS defaults, the profile-selected Chrome channel, Chrome password-manager policy, browser/Raycast extension checklists, and Obsidian vault/plugin seed files. |
| Use app sync/export | Raycast aliases, hotkeys, snippets, Quicklinks, and extensions belong in Raycast Cloud Sync if available on your plan, or Raycast export/import. Anybox links, folders, tags, Smart Lists, Quick Links, snippets, and Anydock profiles sync through iCloud. Chrome Sync is optional and owned by your Google account. |
| Manual by design | App Store purchases, sign-in, password-manager unlock, API keys, SSH-agent approval, default-browser confirmation, macOS privacy prompts, display presets, and app-level hotkeys that depend on your hands, monitors, and existing shortcuts. |
It would look automated for a moment and then drift. Raycast, Anybox, BetterDisplay, and password managers are allowed to change their private storage, encrypt it, sync it, or rewrite it on launch. Groundwork keeps those steps short and repeatable instead of reverse-engineering state that the app owns.
One link workflow
You can choose another capable browser, launcher, or bookmark manager. If you use the installed Chrome, Raycast, and Anybox stack, give each tool one clear job instead of maintaining three competing libraries.
Chrome is the working surface, Raycast is the launcher, and Anybox is the durable bookmark library. A tiny Chrome bookmarks bar and a few Raycast Quicklinks may duplicate important destinations for speed; Anybox remains the source of truth for everything worth keeping.
| Chrome · hot cache | Keep roughly six to ten links you need at a glance, plus an optional Daily folder. This is a visual working set, not the archive. |
| Raycast · front door | Open exact frequent destinations with a small set of native Quicklinks. Use ab for Anybox Search Links and as for Anybox Save Current Tab. |
| Anybox · durable library | Keep all saved links here. Start with Daily, Work/<project>, Personal, and Reference folders; use tags for themes that cross those folders. |
The daily loop is short: save a page to Anybox with as or the browser extension, leave it in Unsorted when you are busy, and retrieve it with ab. Once a week, empty Unsorted, remove dead or duplicated links, and demote anything that no longer deserves space in Chrome or a Raycast Quicklink.
Browsers
| Chrome stable | The managed default for Personal Current and Work Managed. Preview profiles retain it as a compatibility fallback. |
| Chrome Beta | The managed primary browser for Personal Preview and Disposable Experimental on a desktop Mac. It installs beside stable Chrome. |
Groundwork installs the Chrome channel selected by your release posture. It never changes the macOS default-browser association: that confirmation remains your decision. Organization and device policy outrank the profile on managed machines.
Use Chrome without signing in, or sign in if you want Google to sync bookmarks, history, saved passwords, settings, and open tabs. Groundwork does not sign in, enable sync, or put account data into dotfiles. Any browser Groundwork no longer manages remains installed with its data untouched until you decide what to do with it.
Browser extensions
Groundwork keeps the extension source of truth in ~/.local/share/groundwork/browser-extensions.tsv. Run browser-extensions to list the vetted links, or browser-extensions --open on macOS to open them in Chrome through the Chrome Web Store.
| Core | Password manager, uBlock Origin Lite, Anybox Browser Extension, and Obsidian Web Clipper. |
| Privacy | Privacy.com is included as the official virtual-card service link. I could not verify a current official browser extension, so it is not treated as an extension install. |
| Optional privacy | Privacy Badger is available, but keep the extension set small unless you need it; every extension is another trusted code path. |
| Frontend dev | React Developer Tools, Redux DevTools, Vue.js devtools, Angular DevTools for Chromium, and axe DevTools for accessibility. |
$ browser-extensions
$ browser-extensions --browser chrome --tier core --open
$ browser-extensions --browser chrome --tier dev --openPassword manager and autofill
Groundwork installs Bitwarden or 1Password based on the setup choice, but sign-in, autofill provider selection, and SSH-agent approval are intentionally manual. Password managers protect the keys and credentials agents should never see in prompts or dotfiles.
| SSH agent | Sign in to the desktop app, then enable its SSH agent. Bitwarden: Settings → enable SSH agent. 1Password: Settings → Developer → Use the SSH agent. If commits stop signing, unlock the app and retry. See Git for the signing flow. |
| macOS + Safari | System Settings → General → AutoFill & Passwords: turn on Bitwarden and turn off Passwords/iCloud Keychain if Bitwarden is the source of truth. |
| Chrome | Install the Bitwarden extension, sign in, and pin it. Groundwork disables Chrome's built-in password manager by policy. |
| iOS / iPadOS | Install Bitwarden, sign in, then Settings → General → AutoFill & Passwords: enable Bitwarden and disable Passwords if you want the same source of truth on mobile. |
Raycast — the launcher
Raycast is the single biggest quality-of-life app here. One keystroke opens a search box that launches apps, does math, manages windows, remembers your clipboard, and runs little commands — so your hands stay off the mouse. It's meant to take over ⌘Space from Spotlight.
From a shell, open -a <App> is the direct macOS path when the app name is already known. Raycast remains the better path when you want to search rather than remember the exact name.
| Launch & search | Hit the hotkey, type an app or file name, Enter |
| Clipboard history | Everything you've copied, searchable — no more losing what you copied two things ago |
| Window management | Snap windows left/right/full from the keyboard — the default window manager for this setup |
| Quicklinks | Save a keyword that jumps straight to a site or search you use daily |
| Extensions | A store of add-ons — GitHub, Homebrew, and more |
Aliases, Quicklinks, and hotkeys
There are two kinds of Raycast shortcuts, and mixing them up is where people create conflicts. Typed aliases are words you type after Raycast is open. Global hotkeys are key chords that work everywhere. Use lots of aliases, but keep global hotkeys rare and consistent. Anybox Quick Links are a separate optional global text-detection feature, described below.
| Typed aliases | Use short, memorable lowercase triggers such as gh for GitHub, cal for calendar, docs for your docs site, ab for Anybox Search Links, and as for Anybox Save Current Tab. They run after you open Raycast, so they do not collide with macOS shortcuts like ⌘Tab. |
| Good keywords | Prefer two to five characters, tied to the thing you want, and easy to type with one hand. Avoid single letters, full app names, and words you already search for often; those create noisy search results instead of speed. |
| Global hotkeys | Use key chords only for actions you need many times a day: Raycast itself, clipboard history, and window snapping. Keep one mostly-free modifier family, usually ⌃⌥, so your custom shortcuts are easy to remember and easy to audit. |
| Reserved habits | Do not override core macOS/browser muscle memory unless you mean to: ⌘Space for Raycast, ⌘Tab, ⌘Q, ⌘W, ⌘H, browser tab keys, and Mission Control keys. |
Raycast, not Anybox, should replace Spotlight. In System Settings → Keyboard → Keyboard Shortcuts → Spotlight, change or uncheck "Show Spotlight search," then set Raycast's hotkey to ⌘Space (its onboarding offers to do this for you). chezmoi installs Raycast, but this hotkey lives in Raycast/macOS settings, so use Raycast Cloud Sync if it is available on your plan, or export/import a Raycast config to reproduce it.
Browser add-ons live in Chrome. Raycast extensions live inside the Raycast app and come from the Raycast Store. Groundwork cannot silently install or configure Raycast's internal extension database, but it does install a helper on Mac profiles: run raycast-extensions to list the recommended Store entries, or raycast-extensions --open to open them.
$ raycast-extensions
$ raycast-extensions --open
$ raycast-extensions --tier tabs --open
$ raycast-extensions --tier ai --openUsing it day to day
The loop is always the same: tap the hotkey, start typing, press Enter. What you type can be an app name, a math expression (128*1.2), a unit or currency conversion, or part of a filename — Raycast surfaces the best match. A few habits make it sing:
| Clipboard history | Give it one global hotkey in Settings → Extensions, preferably inside the same ⌃⌥ family, then recall anything you copied earlier instead of losing it |
| Window management | Set hotkeys to snap the focused window left / right / full / to another display — no mouse |
| Quicklinks | Keep roughly five to ten exact destinations or parameterized searches you open constantly. Add a daily tag and choose Open With → the Chrome channel selected by your Groundwork profile, either Google Chrome or Google Chrome Beta. In Raycast Settings → Quicklinks, enable the global Prefer Existing Tabs setting to reuse matching open tabs instead of creating duplicates. |
| Aliases & hotkeys | For any command you use a lot, start with a typed alias. Promote it to a global hotkey only when you use it constantly and know it will not shadow macOS or browser defaults. |
| Extensions | Add from the Store — Browser Bookmarks, Browser Tabs, GitHub, Homebrew, Anybox, the VS Code project opener — and search them right from the bar |
Reproducing your Raycast setup on another Mac isn't something chezmoi can do because Raycast keeps aliases, hotkeys, extensions, and Quicklinks internally. Use Raycast Cloud Sync if it is available on your plan; otherwise use Settings → Advanced → Export to a .rayconfig file and Import it on the other machine. Keep full exports out of Git: they are private, not reviewable like text config, and may include settings you did not mean to publish. The important hotkeys to set first are Raycast itself on ⌘Space, window left half, right half, maximize, restore, clipboard history, Browser Bookmarks, Browser Tabs if you use supported browsers, and Anybox link search.
Bookmarks, tabs, and links in Raycast
| Raycast Quicklink | A launcher entry for one exact frequent destination or parameterized search. It is intentionally a small speed layer, not the durable library. |
| Anybox Quick Find | Anybox's search window for the durable library; it can search everything or be scoped to a tag or Smart List. The Raycast Anybox extension exposes the library through Search Links. |
| Anybox Quick Link | An optional global typed-keyword expansion. It is not a Raycast alias or Quicklink and it requires extra system permission. |
| Chrome bookmark | A visible link in the small browser hot cache. Keep only the destinations that earn permanent space in the current working surface. |
| Browser Bookmarks extension | A compatibility bridge for bookmarks that already live in Chrome or Safari. It is useful during migration or when another browser must retain its own library, but it is not the Groundwork source of truth. |
| Browser Tabs | Use for live open tabs in browsers Raycast can read through macOS automation, especially Safari and Chromium-family browsers. |
| Browser add-ons | Install the Anybox and Obsidian Web Clipper add-ons in Chrome with browser-extensions --tier core --open. They are for capturing pages, not for making Raycast itself work. |
Asking Claude, GPT, or Grok from Raycast
There are two good paths. Raycast Pro is the cleanest: use Quick AI from the root Raycast search, AI Chat for longer conversations, AI Commands on selected text, and the model picker when you want Claude, OpenAI, or Grok. No per-model extension setup; Raycast owns the subscription and routing.
The no-subscription path is bring your own keys: install separate ChatGPT, Claude, and Grok extensions from the Store and configure each with its provider API key. It is more fiddly, but it lets you pay providers directly. Run raycast-extensions --tier ai --open to open the relevant Store searches and Raycast AI docs.
If Raycast Settings only shows Anybox under Applications, the Raycast extension is not installed yet. Install the Anybox Raycast extension from the Raycast Store, or run open 'raycast://extensions/anybox/anybox?source=webstore'. Its Save Current Tab commands work through Anybox, and its Search Links command has its own required API Key preference. Copy the key from the Anybox app → Preferences → General, then select the Search Links command row in Raycast Settings and paste it there. Add Raycast aliases ab for Search Links and as for Save Current Tab; these are fast, memorable, and do not compete with global macOS shortcuts.
| Search Tags | On — tags should be searchable from Raycast. |
| Search Folders | On — folders matter once Anybox becomes the shared project/client/teaching link library. |
| Show Tags | On — useful context while scanning results. |
| Show Folders | On — useful context while scanning results. |
| As Icons | Off — list view is faster to scan from Raycast. |
| Prefer Link Icons in Icons view | Off — only matters if icon view is enabled. |
Anybox — bookmarks
Anybox is the durable source of truth for saved links. It supports nested folders, nested tags, Smart Lists, Quick Find, and iCloud sync, so the library stays useful without depending on one browser's bookmark database.
Using it day to day
Three motions cover it: save, organize, recall.
| Save a link | Use Raycast's as alias, the Anybox browser extension, Anybox's capture hotkey, or the macOS share sheet. Leave the link in Unsorted when speed matters. |
| Organize | Move links into folders such as Daily, Work/<project>, Personal, and Reference. Add tags for cross-cutting topics instead of creating a second folder tree. |
| Recall | Open Anybox Quick Find or use the Raycast ab alias for Search Links. Both search the durable library. |
An Anybox Quick Link is detected when its keyword is typed anywhere outside Anybox. The keyword must be at least two characters, and Anybox requires macOS Accessibility access to observe it. Groundwork's ordinary path is Raycast aliases and native Quicklinks; enable Anybox Quick Links only when you intentionally want system-wide text detection, and choose uncommon keywords that will not expand during normal typing.
Profiles belong to Anydock, Anybox's favorite-link dock. Use them only when you want different Anydock layouts for work and personal contexts; use folders and tags to organize the actual library.
Run it as a menu-bar app so it's always a keystroke away, and it syncs everything through iCloud to your other devices. Pro removes the small free-library cap, which makes Anybox a real shared bookmark layer for work, home, teaching, and client links.
Anybox links, folders, tags, Smart Lists, Quick Links, snippets, Anydock profiles, and menu-bar behavior are app-owned state. Set them once in Anybox and let iCloud carry them to your other Apple devices. The Anybox API key also stays out of the repo: paste it into the Raycast Anybox command preference by hand so it remains a local secret.
Anybox is bought once from the App Store — the setup can't purchase it for you. Buy and sign in there first; after that it updates and syncs on its own. There is no AI switch you need for this workflow; Anybox is the link library, not the AI layer.
BetterDisplay — resolutions and monitors
BetterDisplay owns the display layer: menu-bar resolution changes, favorite display modes, refresh rates, brightness/DDC controls for supported monitors, and protection against layouts drifting when displays reconnect. Raycast moves windows; BetterDisplay changes the screens those windows live on.
| Resolution menu | Switch between favorite scaled resolutions without digging through System Settings |
| External monitor controls | Adjust brightness, volume, inputs, and color modes on many supported displays |
| Layout protection | Keep laptop and external monitor arrangements stable after sleep, docks, and reconnects |
betterdisplaycli | Use BetterDisplay's CLI, URL schemes, Shortcuts, or Raycast commands for repeatable display setups after the app configuration is stable |
Groundwork does not seed BetterDisplay presets or hotkeys. Those depend on the exact laptop, dock, monitor IDs, refresh rates, and licensing state in front of you. Pick favorites in the app first, then automate with BetterDisplay's supported CLI, Shortcuts, URL schemes, or Raycast only after you know the display setup is stable.
BetterDisplay has a free tier and a paid Pro license. For work or contract teams, check the license before relying on Pro features.
Obsidian — notes
Obsidian is a notes app where every note is a plain markdown file you own. Notes link to each other with [[double brackets]], building a web of ideas you can navigate visually. The setup points it at an iCloud vault so your notes follow you to every Mac and the mobile app.
Groundwork enables Obsidian's Vim mode in managed vault defaults. That keeps notes consistent with Neovim muscle memory: Esc returns to Normal mode, j/k move by line, and editing uses familiar Vim motions.
The wiki from the Knowledge base page is just a folder of markdown — open it as an Obsidian vault and you get the same notes with a visual graph and link-following on top.
Obsidian AI helpers
Obsidian is useful before adding AI. If you do use AI over notes, keep the data flow explicit: local files stay in the vault, plugins get only the keys or local endpoints they need, and agents work from a project folder you can inspect.
| Keep files local | Your vault lives at iCloud Drive/Obsidian/<name>. Right-click the folder and choose Keep Downloaded, or turn off Optimize Mac Storage, so notes are available to editors and agents. |
| Plugin first run | After first launch, restart Obsidian once so Groundwork's auto-installed plugins load before you configure them. |
| Smart Connections | Add your Claude API key or local Ollama URL, then choose the embedding model you want. For a local path, start Ollama so it serves http://localhost:11434, then run ollama pull nomic-embed-text. |
| Whisper | Use it for speech-to-text notes. Point it at a local endpoint if you want speech fully offline. |
| Claude Code over notes | For AI chat over a vault, point Claude Code at the vault or the generated knowledge-wiki folder so changes happen through files you can review. |
The terminal window: Ghostty
Everything in the rest of this guide — the shell, tmux, Neovim — runs inside Ghostty, a fast, modern terminal app themed to match the rest of the setup. It's the window; tmux does the splitting inside it. Worth knowing: ⌘K clears the screen.
Groundwork installs font-jetbrains-mono-nerd-font and sets Ghostty to JetBrainsMono Nerd Font at size 14. The goal is practical readability: code should make 1, l, I, 0, O, and similar shapes easy to tell apart, and the Nerd Font symbols keep prompt and tmux icons from turning into boxes.
$ ghostty +show-config | grep -i font-family
font-family = JetBrainsMono Nerd FontA fresh Ghostty launch opens in your home folder (~). New tabs, windows, and splits inherit the folder you are already working in, so quick side shells stay near the task. tmux owns project persistence and restoration; Ghostty stays a clean window around it.
Communication
Rounding out the set, installed and ready to sign into:
| Slack · Zoom | Team chat and calls |
| Discord | Communities and dev servers |
| Personal messaging |
Uninstalling apps without leaving a mess
Groundwork installs AppCleaner on personal Macs, but it is the fallback, not the universal first step. The installer that owns an app usually knows more about its login items, extensions, privileged helpers, and shared data than a generic cleaner can infer.
- Vendor uninstaller first. If the app includes an uninstall command or removal app, use it.
- Homebrew next. For an app managed by the Brewfile, run
brew uninstall --cask NAME. Add--zaponly after inspecting the cask because zap can remove preferences, caches, and shared resources. - AppCleaner for a plain app. Drag an app that was installed from a DMG or ZIP into AppCleaner, review every related path it proposes, then remove the checked items.
- Personal files stay a separate decision. Projects, documents, media libraries, cloud files, and exported data are not app leftovers. Archive or delete those deliberately.
Use largest ~ before and after cleanup when you want evidence that the space changed. Apple’s Storage settings remain the safest overview for user files and system recommendations.
First-time setup
Hand ⌘Space to Raycast
Free up Spotlight's shortcut (settings above), then set Raycast to ⌘Space. Open it, launch an app, then press it again and try the clipboard history. This is the habit that changes your day.
Confirm the managed Chrome channel
Run groundwork-profile show. Current and Work Managed use Chrome stable; preview profiles use Chrome Beta and retain stable as a fallback. If you want to change the macOS default browser, run defaultbrowser and make that separate choice yourself.
Connect the link workflow
Buy and sign into Anybox from the App Store, enable its menu-bar mode, create the starter folders above, and install its Raycast extension. Paste the Anybox API key into Search Links, assign ab and as, then save and reopen one page. Keep Anybox Quick Links off unless you intentionally want global typed-keyword detection.
Choose your display presets
Open BetterDisplay, mark the resolutions you actually use as favorites, and make sure the menu bar icon is visible. If you use an external display, test brightness and input control.
Open your notes
Launch Obsidian, open the iCloud vault, and make a note. Type [[ and watch it offer to link to other notes — that's the whole idea.