Skip to content

andreivcodes/dotfiles

BranchesTags

Repository files navigation

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
├── Brewfile
├── LICENSE
├── setup.sh
├── 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
│   ├── agents/
│   │   ├── AGENTS.md
│   │   ├── figma-console-mcp-run.sh
│   │   ├── mcp-inventory.json
│   │   ├── scoped-env-run.sh
│   │   ├── versions.sh
│   │   └── skills/
│   ├── codex/
│   │   ├── config.toml
│   │   └── sync-config.sh
│   ├── pi/
│   │   ├── mcp.json
│   │   ├── models.json
│   │   └── pi-acp-zed.sh
│   ├── asimeow/
│   │   └── config.yaml
│   ├── claude/
│   │   ├── mcp.json
│   │   ├── settings.json
│   │   └── statusline.sh
│   └── zed/
│       ├── keymap.json
│       └── settings.json
├── scripts/
│   └── validate.sh
├── preferences/
│   └── system.sh
└── lib/
    └── utils.sh

Installation

Prerequisites

  • macOS (tested on macOS 15.2+)
  • 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, Claude Desktop, 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

bash installers/brew.sh
bash installers/dev.sh
bash installers/kicad-mcps.sh
bash installers/mcp-env.sh
bash installers/ai-tools.sh
bash preferences/system.sh
bash dotfiles/dotfiles.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
  • Claude and Pi Zed launchers that expose only the API keys each process needs
  • Pi ACP fallback pinned to the checked-in version inventory

AI CLI Configuration

This repo manages stable config and launchers for three CLI tools:

  • Codex: 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/models.json, ~/.pi/agent/AGENTS.md, ~/.pi/agent/pi-acp-zed.sh
  • 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
  • Claude Desktop MCP: merged from ~/.claude/desktop-mcp.json into ~/Library/Application Support/Claude/claude_desktop_config.json

Usage is plain:

codex
pi
claude

Authentication is also plain:

codex login
claude auth login
pi
# then run /login inside pi, or export your provider API key

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, Zed prompt databases, 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, FIGMA_ACCESS_TOKEN, UIDOTSH_TOKEN, and NEURALWATT_API_KEY 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.

Pi defaults to the repo-managed NeuralWatt provider in ~/.pi/agent/models.json, using model glm-5.2, defaultThinkingLevel xhigh, and NEURALWATT_API_KEY from the local shell environment.

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, Claude Desktop, 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.

Figma Console MCP runs through the scoped launcher and receives only FIGMA_ACCESS_TOKEN. The bridge package and all stdio proxy packages use exact versions from dotfiles/agents/versions.sh. 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

Zed Configuration

  • Codex, Claude Code, and Pi agent server support
  • Prettier formatters for JavaScript, TypeScript, and TSX
  • Stable Rust rustfmt support without an undeclared nightly toolchain
  • Git gutter and inline blame
  • Integrated zsh terminal
  • System-aware One Light / One Dark theme

Desktop AI Apps

Full setup also installs:

  • Claude Desktop via the official Homebrew claude cask
  • T3 Code via the official Homebrew t3-code cask

The Dock installer places both right after Zed Preview 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, a Gitleaks current-tree scan, and whitespace. 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. Zed links only settings.json and keymap.json, leaving runtime databases under the local ~/.config/zed/ directory.

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 Claude Desktop is not showing MCP tools, fully quit and restart the app, then inspect ~/Library/Logs/Claude/mcp*.log.

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. If NeuralWatt is not available in Pi, verify ~/.pi/agent/models.json exists and NEURALWATT_API_KEY is set in ~/.zshrc.local.

Completion Not Working

rm -f ~/.zcompdump
exec zsh

Homebrew Issues

brew doctor
brew cleanup
brew update
brew upgrade

Security Notes

  • .gitignore keeps secrets and local-only files out of the repo
  • Untrusted npm and local MCP child processes receive only explicitly allowlisted secrets
  • Codex and Zed retain the deliberately permissive trust/tool posture represented by the checked-in config
  • Auth, sessions, generated plugin state, and editor databases stay tool-managed

Resources

License

MIT

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages