Dotfiles

Personal macOS configuration files and development environment setup.

Quick Start

git clone https://github.com/andreivcodes/dotfiles.git ~/git/dotfiles
cd ~/git/dotfiles
./setup.sh

What's Included

• Brewfile: Declarative package management for Homebrew CLI tools and apps
• Shell Configuration: Performance-optimized .zshrc with lazy loading
• AI CLI Configuration: Shared Codex, Claude Code, and Pi setup
• Shared Agent Rules & Skills: One canonical instructions file, synced repo skills, and preserved external skill installs
• Development Environment: Node.js (via NVM), Rust, Bun, and essential CLI tools
• Installation Scripts: Automated setup and symlink management

Repository Structure

dotfiles/
├── README.md
├── AGENTS.md
├── Brewfile
├── LICENSE
├── setup.sh
├── .zshrc.local.example
├── installers/
│   ├── all.sh
│   ├── ai-tools.sh
│   ├── brew.sh
│   ├── dev.sh
│   ├── dock.sh
│   ├── kicad-mcps.sh
│   ├── mcp-env.sh
│   └── timemachine-exclude.sh
├── dotfiles/
│   ├── dotfiles.sh
│   ├── .zshrc
│   ├── .npmrc
│   ├── .bunfig.toml
│   ├── .yarnrc.yml
│   ├── agents/
│   │   ├── AGENTS.md
│   │   ├── mcp-inventory.json
│   │   ├── scoped-env-run.sh
│   │   ├── versions.sh
│   │   └── skills/
│   ├── asimeow/
│   │   └── config.yaml
│   ├── claude/
│   │   ├── CLAUDE.md
│   │   ├── mcp.json
│   │   ├── settings.json
│   │   └── statusline.sh
│   ├── codex/
│   │   ├── config.toml
│   │   └── sync-config.sh
│   ├── pi/
│   │   └── mcp.json
│   └── pnpm/
│       └── rc
├── scripts/
│   └── validate.sh
├── preferences/
│   └── system.sh
└── lib/
    └── utils.sh

Installation

Prerequisites

• macOS 26 or newer (preferences/system.sh gates its Spotlight clipboard-history setting on major version 26+; everything else degrades gracefully on older releases)
• internet access for Homebrew, npm, git, and installer downloads

Full Setup (Recommended)

git clone https://github.com/andreivcodes/dotfiles.git ~/git/dotfiles
cd ~/git/dotfiles
./setup.sh

This will:

• Install all Homebrew packages and applications
• Set up Node.js, Bun, and Rust development environments
• Install Codex, Claude Code, Pi, Pi ACP, T3 Code, Agent Browser, Railway CLI, and Vercel CLI through one canonical owner for each tool
• Install pinned KiCad and KiPilot MCP sources plus the verified FreeRouting JAR
• Prompt for MCP API keys used by the shared AI tool configs
• Configure macOS system preferences
• Create symlinks for shell, editor, and shared AI CLI configs
• Configure Dock layout
• Set up Time Machine exclusions for development directories
• Run the repository validation suite and return a nonzero status if any setup stage failed

Time Machine Exclusions

The dotfiles setup installs asimeow, links the repo-managed config to ~/.config/asimeow/config.yaml, runs an immediate exclusion pass, and then starts the native Homebrew service for ongoing scans.

The managed config intentionally keeps automatic roots outside privacy-protected locations like ~/Desktop, ~/Documents, and ~/Downloads. Background services are less reliable there on modern macOS, so the defaults focus on common unprotected dev roots and keep the scheduled setup predictable.

Defaults are:

• ~/git
• ~/src
• ~/code
• ~/dev
• ~/work

User-level dependency caches are also registered directly as exclusions outside the asimeow work roots. The installer resolves the actual cache locations where possible and excludes them directly. Examples include:

• ~/Library/Caches
• npm cache
• pnpm store
• Bun global cache
• Cargo registry and git caches
• Go build and module caches
• pip and uv caches
• Gradle caches and wrapper distributions
• Maven local repository
• Yarn cache

To change automatic roots or rules, edit the repo-managed config at dotfiles/asimeow/config.yaml and resync dotfiles:

bash dotfiles/dotfiles.sh
bash installers/timemachine-exclude.sh

asimeow itself scans on the schedule provided by its Homebrew service, which is currently every 6 hours upstream.

Partial Setup

Run these in order. dotfiles/dotfiles.sh must precede installers/ai-tools.sh, because the MCP registrations that ai-tools.sh writes point at the scoped launcher (~/.agents/scoped-env-run.sh) that dotfiles.sh links into place.

bash installers/brew.sh
bash installers/dev.sh
bash installers/kicad-mcps.sh
bash installers/mcp-env.sh
bash dotfiles/dotfiles.sh
bash installers/ai-tools.sh
bash preferences/system.sh
bash installers/dock.sh
bash installers/timemachine-exclude.sh
./scripts/validate.sh

Key Features

Shell Configuration

• Lazy loading for nvm, cargo, and rustup
• 100k command history with deduplication and sharing across sessions
• Git aliases for common workflows
• Oh My Zsh-managed completion initialization without a duplicate compinit pass
• Pi ACP fallback pinned to the checked-in version inventory

AI CLI Configuration

This repo manages stable config and launchers for the Codex desktop app and two CLI tools:

• Codex (via the ChatGPT desktop app): stable settings from dotfiles/codex/config.toml are merged into the regular, app-owned ~/.codex/config.toml; ~/.codex/AGENTS.md remains linked
• Pi: ~/.pi/agent/mcp.json, ~/.pi/agent/AGENTS.md
• Claude Code: ~/.claude/settings.json, ~/.claude/CLAUDE.md, ~/.claude/mcp.json, and ~/.claude/statusline.sh; installers/ai-tools.sh reconciles the template into user-scope MCP registrations

Usage is plain:

pi
claude
# Codex runs inside the ChatGPT desktop app

Authentication is also plain:

claude auth login
pi
# then run /login inside pi, or export your provider API key
# Codex: sign in from the ChatGPT desktop app

The repo only manages stable config files and shared skill infrastructure. Codex project trust, marketplaces, plugin state, and the app-generated node_repl stanza remain in the live config and survive every sync. Auth, sessions, Pi package state, and other mutable runtime state stay in the tools' native user locations.

During setup, installers/mcp-env.sh prompts for CONTEXT7_API_KEY, EXA_API_KEY, and UIDOTSH_TOKEN and writes them to mode-600 ~/.zshrc.local. Secrets are not copied into launchctl; GUI clients use ~/.agents/scoped-env-run.sh with explicit per-process allowlists.

dotfiles/agents/mcp-inventory.json documents capability ownership per client. Codex uses the installed Context7 and Vercel plugins plus native web search, so their redundant Codex MCP entries are removed. Claude Code and Pi retain MCP equivalents because those Codex plugins do not provide capabilities to those clients. Exa remains available there as a paid fallback after native search; the shared agent rules no longer select it by default.

Every client — Codex, Claude Code, and Pi — reaches Figma through the same pinned Hopp Figma MCP Bridge, which tunnels over SSH to the Figma Desktop plugin on the devbox. The legacy Figma Console MCP has been removed, along with its FIGMA_ACCESS_TOKEN prompt and scoped launcher, because the bridge authenticates through the Figma Desktop session rather than a personal access token. Figma's official web, Dev Mode, and desktop-extension connectors are intentionally excluded everywhere. The Hopp bridge and every stdio proxy package are pinned to exact versions in dotfiles/agents/versions.sh. Versions that JSON and TOML cannot interpolate — the FreeRouting JAR path and the bridge's remote install path — are enforced by the embedded version pins check in scripts/validate.sh, so bumping the inventory without updating the client configs fails validation instead of silently pointing a server at a path that was never installed. Codex, Claude Code, and Pi retain the specialized kicad, kipilot, and uidotsh MCPs. Codex's node_repl remains app-owned because the Browser, Chrome, and Computer Use plugins depend on its app-generated paths and hashes.

installers/kicad-mcps.sh provisions the pinned KiCad and KiPilot source commits, Python environments, OpenJDK, KiCad CLI dependency, and checksum-verified FreeRouting JAR. A dirty existing MCP checkout is never overwritten.

Shared Skills

• Repo skills placed under dotfiles/agents/skills are linked into the shared skills directory at ~/.agents/skills
• Skills installed separately, including skills.sh symlink installs, are preserved during sync
• Codex and Claude Code native skill directories are linked to that shared location
• Pi auto-discovers ~/.agents/skills directly, and installers/ai-tools.sh also records that shared path in Pi's mutable settings.json
• One canonical rules file in dotfiles/agents/AGENTS.md is linked into each tool's documented shared config location

Because ~/.codex/skills and ~/.claude/skills both point at the same shared directory, and Pi reads ~/.agents/skills directly, global skills.sh installs done as symlinks stay compatible with this repo's setup.

Browser Automation

agent-browser is installed through Homebrew on macOS:

brew install agent-browser
agent-browser install

The first command installs the CLI. The second downloads Chrome for Testing, which agent-browser uses by default. The shared AGENTS.md rules tell Codex, Claude Code, and Pi to use it for browser automation tasks.

Brewfile Package Management

Use the checked-in Brewfile directly:

cd ~/git/dotfiles
brew bundle install
brew bundle check
brew bundle cleanup

brew bundle install --file ~/git/dotfiles/Brewfile
brew bundle check --file ~/git/dotfiles/Brewfile

Desktop AI Apps

Full setup also installs:

• ChatGPT desktop app (includes Codex) via the official Homebrew chatgpt cask
• T3 Code (nightly channel) via the official Homebrew t3-code@nightly cask

The Dock installer places both in the Dock when they are installed.

Performance Testing

Measure Shell Startup Time

/usr/bin/time zsh -i -c exit

Expected result with the current lazy-loading setup: roughly 0.05-0.15s.

Profile Shell Initialization

zmodload zsh/zprof
exec zsh
zprof

Maintenance

Updating Packages

brew update && brew upgrade
omz update

cd ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions && git pull
cd ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting && git pull

MCP and npm-agent versions are intentionally pinned in dotfiles/agents/versions.sh. Update that inventory deliberately, update matching JSON launch arguments, then validate the repository.

Validation

./scripts/validate.sh

The validator checks shell lint and syntax, JSON/TOML/YAML parsing, executable modes, exact MCP inventory parity, version pinning, embedded version pins across client configs, a Gitleaks current-tree scan, and whitespace. Every check fails closed when the tool it needs is unavailable, so a green run means the checks actually executed rather than silently skipping. Use gitleaks git . --redact separately when auditing historical commits; rotate a leaked credential before rewriting public history.

Syncing Changes

Stable single-file configs are symlinked into the home directory. Codex is the exception: dotfiles/codex/sync-config.sh merges the repo's stable settings into a regular ~/.codex/config.toml, preserving app-owned projects, plugin state, marketplaces, and node_repl.

Troubleshooting

Slow Shell Startup

1. Profile the shell with zprof
2. Check that nvm and cargo are still lazy-loaded
3. Trim unused Oh My Zsh plugins
4. Run brew doctor

AI CLIs Not Working

Verify the commands resolve correctly:

type codex
type pi
type pi-acp
type claude
type agent-browser

If a tool is missing, install it with:

brew install --cask codex
curl -fsSL https://claude.ai/install.sh | bash
brew install agent-browser
agent-browser install
brew install railway
bash installers/dev.sh
bash installers/ai-tools.sh
bash installers/kicad-mcps.sh

If Claude Code is installed but not loading the shared MCP registrations, rerun bash installers/ai-tools.sh and inspect claude mcp list.

If Pi is installed but not seeing the shared MCP servers, verify ~/.pi/agent/mcp.json exists, confirm pi list includes pi-mcp-adapter, and restart Pi so the adapter reloads.

Completion Not Working

rm -f ~/.zcompdump
exec zsh

Homebrew Issues

brew doctor
brew cleanup
brew update
brew upgrade

Security Notes

• Secrets live only in mode-600 ~/.zshrc.local, never in the repo. .gitignore uses anchored patterns rather than unbounded globs like *secret*, which silently swallow legitimately named files; the Gitleaks check in scripts/validate.sh is the actual backstop against a committed credential
• No secret is passed in argv or a URL query string. Every client authenticates the uidotsh server with an Authorization: Bearer header (Claude Code), a bearer_token_env_var (Codex), or a bearerTokenEnv (Pi), so tokens stay out of ps output and server-side request logs
• Untrusted npm and local MCP child processes receive only explicitly allowlisted secrets via ~/.agents/scoped-env-run.sh, which strips every other secret-shaped variable from the inherited environment
• npm, pnpm, Yarn, and Bun each enforce a one-day minimum release age, so a freshly published (or freshly compromised) dependency version cannot be installed on the day it lands
• Codex retains the deliberately permissive trust/tool posture represented by the checked-in config. That posture is what makes the two points above matter: with approval_policy = "never" and sandbox_mode = "danger-full-access", the scoped launcher allowlist is the boundary that limits what a compromised MCP server can read
• Auth, sessions, generated plugin state, and editor databases stay tool-managed

Resources

• Homebrew Documentation
• Homebrew Bundle
• Oh My Zsh

License

MIT