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.

#Browsers

Browser extensions

Groundwork keeps the extension source of truth in ~/.local/share/groundwork/browser-extensions.tsv. Run browser-extensions to list the vetted links. On macOS, add --open to open them in Zen, Chrome, or Dia. Chrome and Dia use Chrome Web Store links; Zen uses Firefox Add-ons.

$ browser-extensions
$ browser-extensions --browser zen --tier core --open
$ browser-extensions --browser chrome --tier dev --open

Password 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.

#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.

Aliases, Quicklinks, and hotkeys

There are two kinds of shortcuts, and mixing them up is where people create conflicts. Typed aliases are words you type after Raycast or Anybox is already open. Global hotkeys are key chords that work everywhere. Use lots of aliases, but keep global hotkeys rare and consistent.

$ raycast-extensions
$ raycast-extensions --open
$ raycast-extensions --tier tabs --open
$ raycast-extensions --tier ai --open

Using 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:

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

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.

#Anybox — bookmarks

Anybox keeps your links organized and a keystroke away. It can live in the menu bar, group links into profiles (one set for work, another for personal), and jump to any of them with a keyword. It syncs across your devices through iCloud.

Using it day to day

Three motions cover it: save, organize, recall.

For Anybox Quick Links, use the same typed-keyword convention as Raycast: short lowercase triggers for places you open constantly, such as gh, cal, docs, or a project nickname. Quick Link keywords are typed after opening Anybox, so they are safer than global hotkeys; reserve actual key chords for capture and search actions you use all day.

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.

#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.

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.

#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.

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.

#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.

$ ghostty +show-config | grep -i font-family
font-family = JetBrainsMono Nerd Font

#Communication

Rounding out the set, installed and ready to sign into:

#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.

1. Vendor uninstaller first. If the app includes an uninstall command or removal app, use it.
2. Homebrew next. For an app managed by the Brewfile, run brew uninstall --cask NAME. Add --zap only after inspecting the cask because zap can remove preferences, caches, and shared resources.
3. 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.
4. 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

#Going deeper

• Zen · Raycast manual · macOS desktop
• Anybox · BetterDisplay · Obsidian help
• Apple: uninstall apps · Apple: optimize storage · Homebrew cask zap · AppCleaner