context-bar

dotfiles

Personal macOS configuration files. Clone this repo on a fresh Mac and run a few commands to get a fully configured development environment.

Structure

.dotfiles/
├── Makefile              # Main entry point (make install, make brew, etc.)
├── bootstrap.sh          # Pulls latest changes, inits submodules, creates symlinks
├── brew_itself.sh        # Installs Homebrew and Oh My Zsh
├── Brewfile              # All Homebrew formulae and casks
├── macos.sh              # macOS system preferences and security hardening
├── .claude/
│   ├── CLAUDE.md                       # Global Claude Code instructions (symlinked to ~/.claude/)
│   ├── settings.json                   # Claude Code permissions and hooks (symlinked to ~/.claude/)
│   ├── sdlc.md                         # SDLC guide v1.1.0 (symlinked to ~/.claude/)
│   ├── settings.local.json             # Template for project deny rules (not symlinked)
│   ├── scripts/update-skills.sh        # Pulls every ~/code/claude-* skill repo (run by launchd + alias)
│   └── launchd/                        # LaunchAgents (symlinked to ~/Library/LaunchAgents/)
│       └── com.mathifonseca.claude-skills-update.plist
├── git/
│   ├── .gitconfig        # Git config with delta pager (symlinked to ~)
│   └── .gitignore_global # Global gitignore (symlinked to ~)
├── ghostty/
│   └── config            # Ghostty terminal config (symlinked to ~/.config/ghostty/)
├── starship/
│   └── starship.toml     # Starship prompt config (symlinked to ~/.config/)
├── shell/
│   └── .hushlogin        # Suppresses "Last login" message (symlinked to ~)
└── zsh/
    ├── .zshrc            # Main shell config (symlinked to ~)
    └── custom/
        ├── aliases.zsh   # Custom aliases (auto-loaded by Oh My Zsh)
        ├── path.zsh      # PATH modifications (auto-loaded by Oh My Zsh)
        ├── functions/
        │   └── git_remerge   # Autoloaded shell function
        └── plugins/
            ├── zsh-autosuggestions/     # (git submodule)
            └── zsh-syntax-highlighting/ # (git submodule)

Fresh Mac Setup

1. Install Xcode Command Line Tools

xcode-select --install

2. Clone this repo

mkdir -p ~/code
git clone git@github.com:mathifonseca/dotfiles.git ~/code/.dotfiles
cd ~/code/.dotfiles

The $DOTFILES env var is resolved dynamically from the ~/.zshrc symlink, so the clone path is not hardcoded — but ~/code/.dotfiles is the canonical location.

3. Install Homebrew and Oh My Zsh

./brew_itself.sh

This installs Homebrew and Oh My Zsh.

4. Install everything

make install

This runs all steps in order:

• Initializes git submodules (zsh-autosuggestions, zsh-syntax-highlighting)
• Creates symlinks (.zshrc, .gitconfig, .hushlogin, Ghostty config, Starship config, Claude Code config)
• Installs all Homebrew packages and casks
• Applies macOS system preferences and security hardening

Or run individual steps:

make bootstrap  # just submodules + symlinks
make brew       # just Homebrew packages
make macos      # just macOS preferences
make symlinks   # just symlinks

5. Post-setup

Node.js is managed via nvm, not Homebrew. After setup:

nvm install --lts

GSD (Get Shit Done) is the workflow framework that backs every hook referenced in .claude/settings.json (gsd-context-monitor, gsd-prompt-guard, gsd-statusline, etc.). It is not installed by make install — install it separately following the instructions at mathifonseca/get-shit-done. Until it's installed, Claude Code will emit hook errors at session start.

Re-run the GSD installer on every fresh machine. The hook commands in .claude/settings.json contain absolute paths to the active nvm node binary (e.g. ~/.nvm/versions/node/v24.15.0/bin/node), rewritten by the installer to work in non-interactive shells. After bootstrapping a new machine, npx get-shit-done-cc@latest --claude --global will rewrite those paths to match the local node version.

Claude Code mods live in .claude/mods/ (currently context-bar, the context-window bar above the prompt). They are not symlinked: they are installed as plugins from a local marketplace, and that registration lives in ~/.claude/settings.json, which is not tracked. On a fresh machine, run once:

claude plugin marketplace add ~/code/.dotfiles/.claude/mods/context-bar
claude plugin install context-bar@mathi-mods --scope user

(Adjust the path if the repo is cloned elsewhere.) See Claude Code mods.

Restart your terminal (or source ~/.zshrc) to pick up all changes.

Manual Steps

Some things can't be automated:

• Add user home folder to Finder sidebar
• Delete unused tags in Finder
• Set up collapsible Dock
• Sign in to apps (1Password, Chrome, Slack, Spotify, etc.)
• Enable FileVault if not already on (System Settings > Privacy & Security > FileVault)

What Gets Installed

Homebrew Formulae

Modern CLI Replacements

These tools replace classic Unix commands with faster, more user-friendly alternatives:

Aliases are configured so classic command names use the modern tools:

fd, rg, fzf, jq, and tldr are used by their own names. zoxide replaces the z command automatically.

Casks (GUI Apps)

Shell Setup

Oh My Zsh Plugins

Custom Aliases

Custom Functions

Key Bindings

Prompt

Uses Starship cross-shell prompt with custom config:

• Directory path (truncated to git root)
• Git branch + status + lines added/removed
• Language versions (Node, Go, Java) shown when relevant
• Command duration for slow commands (>2s)
• Current time on the right side

Terminal

Uses Ghostty with:

• Chalk theme
• Fira Code font (size 14)
• Slight transparency with background blur
• Non-blinking bar cursor
• Auto-copy on select
• Tab/split state restored on restart

Claude Code

Configuration for Claude Code, Anthropic's CLI for AI-assisted development. Files are symlinked to ~/.claude/.

Claude Code mods

.claude/mods/context-bar/ draws the context window as a stacked bar above the prompt, one color per /context category, with a legend. Toggle it with /context-bar.

It is a plugin, so it only works once installed (see the post-setup step above). To change it, edit the files in the repo and run /reload-plugins in Claude Code; no reinstall needed. The marketplace is named mathi-mods; add further mods under .claude/mods/ and list them in that folder's marketplace.json.

SDLC Guide

The sdlc.md file is a portable, versioned methodology covering 20 topics: change workflow, git hygiene, planning, testing (including frontend performance optimization), documentation, code quality, design principles, observability, database migrations, dependency management, demo-readiness, agent-ready API design, CI/CD, and AI collaboration patterns.

Distilled from building a production payments platform (34 phases, 5 milestones, 2,793+ tests) with Claude Code.

Using it in a project: Reference the version in the project's CLAUDE.md:

## SDLC
This project follows the [SDLC guide v1.1.0](~/.claude/sdlc.md).

What's NOT tracked here

Claude Code generates runtime state in ~/.claude/ that is machine-specific and should not be version-controlled:

• sessions/, history.jsonl — conversation history
• cache/, file-history/, image-cache/, paste-cache/ — caches
• projects/ — per-project auto-generated memory
• dev-mods/ — scratch folder where mods are written before being moved to .claude/mods/
• get-shit-done/, agents/, hooks/, plugins/ — installed tools (managed by GSD's gsd:update)
• telemetry/, tasks/, plans/, backups/ — runtime state

Git Config

Versioned at git/.gitconfig, symlinked to ~/.gitconfig:

• delta as the pager (side-by-side, line numbers, syntax highlighting)
• zdiff3 conflict style for clearer merge conflicts
• SourceTree as difftool/mergetool
• Global gitignore (.DS_Store, *~)

macOS Preferences

The macos.sh script configures system-wide preferences via defaults write. Here's what it touches:

Inspiration

• mathiasbynens/dotfiles
• dnsmichi/dotfiles
• driesvints/dotfiles