Dylan's Dotfiles

A comprehensive personal environment management system for macOS. This repository serves as the central hub for customizing, configuring, and maintaining your development environment with AI-assisted automation.

🚀 Quick Start

# Clone this repository
git clone https://github.com/dylan-isaac/dotfiles.git ~/Projects/dotfiles

# Run the installation script
cd ~/Projects/dotfiles
./install.sh

# Or install with a specific profile
./install.sh --profile=work

# Or use the AI-enhanced installation analyzer
./bin/install-analyzer.sh

Installation Options

# Skip installing applications
./install.sh --skip-apps

# Quick mode - skip all Homebrew operations and installations that are already complete
./install.sh --quick

# Config-only mode - only perform symlinks and configuration, no installations
./install.sh --config-only

# Install with a specific profile
./install.sh --profile=<profile_name>

# Combine options
./install.sh --quick --skip-apps --profile=minimal
./install.sh --config-only --profile=work

# Use AI-powered installation analyzer
./bin/install-analyzer.sh --ai=goose --profile=work
./bin/install-analyzer.sh --ai=pydantic --verbose

AI-Enhanced Installation

The dotfiles include an AI-powered installation analyzer that:

Runs the installation process and captures its output
Uses AI (either Goose or PydanticAI) to analyze the results
Determines if the installation was successful
Creates a detailed remediation plan for any issues
Provides contextually relevant advice based on your system

# Run installation with AI analysis (default: PydanticAI)
./bin/install-analyzer.sh

# Choose which AI engine to use
./bin/install-analyzer.sh --ai=goose
./bin/install-analyzer.sh --ai=pydantic

# Show verbose installation output
./bin/install-analyzer.sh --verbose

# Pass any standard install.sh arguments
./bin/install-analyzer.sh --profile=work --skip-apps

# Use the convenient wrapper script
./bin/dotfiles-analyzer --ai=goose --verbose

The analyzer saves all logs and analysis to a timestamped directory in /tmp/ for your reference.

For detailed usage instructions and troubleshooting, see the Installation Analyzer documentation.

📦 System Overview

This dotfiles repository is designed as a complete system with several key components:

Configuration Management: Core configurations for your shell, tools, and applications
Profile System: Simple installation profiles for different environments (personal, work, server)
AI Tools Integration: Setup for AI coding assistants and workflows
Installation Automation: Scripts to set up your environment consistently
Documentation: README files in each directory explaining its purpose

Directory Structure

.
├── README.md          # Main documentation (you are here)
├── CHANGELOG.md       # System modification history
├── bin/               # Core scripts and utilities
├── config/            # Configuration files for all tools
│   └── templates/     # Profile-specific templates
│       ├── personal/  # Personal profile templates
│       ├── work/      # Work profile templates
│       └── server/    # Server profile templates
├── contexts/          # Context files for AI tools and reference
├── examples/          # Example configuration templates
├── packages/          # Package management (Homebrew, npm, etc.)
│   ├── Brewfile.personal # Personal profile Homebrew packages
│   ├── Brewfile.work     # Work profile Homebrew packages
│   └── Brewfile.server   # Server profile Homebrew packages
├── scripts/           # Installation and setup scripts
└── tests/             # Test scripts to verify functionality

Each directory contains its own README with detailed information about its purpose and how to modify its contents.

🔧 Components

Shell Setup

Zsh configuration with Oh My Zsh
Starship prompt customization
Modern CLI alternatives:
- eza instead of ls
- bat instead of cat
- ripgrep instead of grep
- zoxide instead of cd

Development Tools

Git configuration
Node.js setup with nvm
Python setup with pyenv and UV (modern Python package manager)
Other development tools

Security Features

Git security check for detecting sensitive information
API key leak detection in code changes
Environment placeholder verification

macOS Configuration

System preferences
Finder preferences
Dock configuration
Safari development settings
Security & privacy settings

🤖 AI Coding Tools

The dotfiles include setup for these AI coding assistants:

Aider - A terminal-based AI pair programming tool
Goose - Block's AI agent for software development
Repomix - Pack your codebase into a single file for LLMs
Firecrawl - MCP server for web scraping and data extraction
Claude Task Master - AI-powered task management system for Cursor
Codex CLI - Lightweight coding agent that runs in your terminal
Claude Code CLI - Command-line interface for interacting with Claude models for coding tasks
AI Developer Workflows (ADW) - Automated coding workflows using the Director pattern
Context Clip - Utility for accessing context files from the command line

Codex CLI

Codex CLI is a lightweight coding agent from OpenAI that runs in your terminal:

# Run Codex interactively
codex

# Run with a prompt as input
codex "explain this codebase to me"

# Run in 'Full Auto' mode
codex --approval-mode full-auto "create a todo-list app"

Codex can:

Scaffold code and run it inside a secure sandbox
Install missing dependencies when needed
Search repositories and understand codebases
Make targeted file edits with your approval

It requires your OpenAI API key, which is automatically sourced from the environment variables in your local configuration file (.zshrc.local).

Claude Code CLI

The Claude Code CLI is a command-line tool from Anthropic that allows you to interact with Claude models specifically for coding-related tasks directly from your terminal.

# Example usage (replace with actual commands when known)
claude-code "Refactor this Python function to be more efficient" --file my_script.py

This tool requires your Anthropic API key (ANTHROPIC_API_KEY) to be set in your environment, typically within your local configuration file (.zshrc.local).

Context Clip

The context-clip utility provides easy access to context files from the command line:

# Copy a context file to clipboard
context-clip ADW

# List available context files
context-clip --list

# Print context to stdout or pipe to other tools
context-clip -p system-prompt
context-clip ADW | grep Director

# Send context directly to AI tools
context-clip -g architecture  # Open in Goose
context-clip -a prompt        # Open in Aider

# Use context in AI workflows
context-clip -w refactor ADW  # Use ADW context in refactor workflow

# Save context to a file
context-clip -s output.md ADW

# Tab completion is available
context-clip [TAB]  # Press Tab to see available contexts

This makes it easy to reuse your context files in various AI-assisted coding workflows. The command features tab completion for context names, making it even faster to access your frequently used contexts.

Claude Task Master

Claude Task Master is an AI-powered task management system designed for Cursor. It helps break down projects into manageable tasks and subtasks.

# List all tasks in a project
task-master list

# Show the next task to work on based on dependencies and status
task-master next

# Show details of a specific task
task-master show <id>

# Generate tasks from a PRD
task-master parse-prd --file=scripts/prd.txt

# Expand a task into subtasks
task-master expand --id=<id>

# Analyze task complexity
task-master analyze-complexity

# Update task status
task-master set-status --id=<id> --status=in-progress

When starting a new project, create a PRD in scripts/prd.txt, then use task-master parse-prd to generate your initial tasks. The system handles dependencies, priorities, and can break complex tasks into manageable subtasks.

Claude Task Master works best when used with Cursor AI. You can ask the AI questions like:

"What's the next task I should work on?"
"Help me implement task 3"
"I've completed task 2, what should I do next?"

For full documentation, see the Claude Task Master GitHub repository.

Goose Profile Configuration

Goose configurations are profile-specific, allowing different setups for personal and work environments:

# Personal profile uses Anthropic models by default
./install.sh --profile=personal

# Work profile typically uses OpenAI models
./install.sh --profile=work

The configuration files are located at:

Default: config/goose/config.yaml
Profile-specific: config/templates/<profile>/goose/config.yaml

The system prefers gpt-4o over older models like gpt-4-turbo. You can check and update the current configuration:

# View current Goose config
cat ~/.config/goose/config.yaml

# Create a profile-specific config (if it doesn't exist)
mkdir -p ~/Projects/dotfiles/config/templates/personal/goose
cp ~/Projects/dotfiles/config/goose/config.yaml ~/Projects/dotfiles/config/templates/personal/goose/
# Then edit to use gpt-4o or your preferred model

Troubleshooting: If Goose is not using your configured model, check ~/.zshrc.local for environment variables like GOOSE_MODEL or GOOSE_PROVIDER that override your configuration. The install script will detect and offer to remove these variables automatically, but you can also remove them manually.

AI Developer Workflows

The system supports two ADW implementations:

1. Classic Director Pattern

The original Director pattern (described in contexts/ADW.md) enables these automated workflows:

# Run a workflow
ai-workflow workflow-name

# List available workflows
ai-workflow --list

# Run with custom task description
ai-workflow "Add input validation to this function" 

# Include files for context
ai-workflow "Update error handling" --files bin/director.py

2. PydanticAI-based Implementation

A modern, type-safe implementation using the PydanticAI agent system:

# Run a workflow with enhanced features
pai-workflow workflow-name

# List available workflows
pai-workflow --list

# Run with custom prompt
pai-workflow workflow-name --prompt="Task description"

Key features of the PydanticAI implementation:

Type Safety: Fully typed with Pydantic models
Iteration-Aware Prompting: Customized prompts for each iteration
Structured Evaluation: Detailed metrics for progress tracking
Failure Analysis: Comprehensive debugging information

See contexts/ADW.md for detailed documentation on both implementations.

Browser Automation with Goose

The system includes Goose extensions for browser automation:

# Run the GitHub stars analyzer
goose "Scrape and summarize the content from https://example.com"

# Run web scraping with Firecrawl MCP
goose "Research and summarize recent developments in AI safety"

# Add an extension to your Goose config for automatic loading
vim ~/.config/goose/config.yaml

Web Scraping with Firecrawl

The system includes integration with Firecrawl MCP for advanced web scraping:

# Configure your Firecrawl API key (already set up in templates)
export FIRECRAWL_API_KEY="your_api_key_here"

# Use Goose with Firecrawl for web research
goose "Extract product information from https://store.example.com"

Repository Context with Repomix

The system includes optimized Repomix integration for generating compact code representations:

# Generate repository context in XML format (with compression)
context

# Generate context in Markdown format
context-md

# Generate full context (without compression)
context-full

# Generate context but preserve comments
context-keep

# Generate context for specific directories
context-src                    # Only include src directory
context --include="api/**"     # Only include api directory
context --exclude="*.test.js"  # Exclude test files

# Minimal context (code-only, no docs/tests)
context-code                   # Exclude documentation files
context-min                    # Exclude docs and tests (most compact)

The Repomix configuration is optimized to reduce output size by intelligently:

Filtering file types: Only includes relevant code files (.py, .js, .ts, etc.)
Excluding noise: Removes package locks, build artifacts, and binary files
Compressing code: Retains structure while removing implementation details
Skipping tests: Optional exclusion of test files that add bulk
Limiting documentation: Options to exclude Markdown and doc directories

This approach typically reduces token usage by 40-60% compared to standard code exports.

To customize your Repomix configuration:

# Edit the global configuration
vim ~/Projects/dotfiles/config/ai/repomix.config.json

# Apply changes by reinstalling your dotfiles
./install.sh

Documentation Generation with Repomix

The system includes a tool for generating comprehensive documentation:

# Generate documentation for a component
./bin/generate-docs.sh bin

# Copy documentation to clipboard
./bin/generate-docs.sh --clipboard config/profiles

# Specify custom template
./bin/generate-docs.sh --template=my-template.md tests

🔐 Sensitive Configuration

All machine-specific configuration is stored in the config/local/ directory, which is excluded from git by .gitignore.

The install script will:

Create the config/local/ directory
Create machine-specific config files from templates
Symlink these files to your home directory

Key local config files:

config/local/.zshrc.local - Machine-specific zsh settings and API keys
config/local/ai/aider.conf.yml - Aider configuration
config/local/ai/.env - Aider environment variables

📋 Profile System

The profile system allows you to easily install configurations for different environments:

# Install with the default personal profile
./install.sh

# Install with the work profile
./install.sh --profile=work

# Install with the server profile
./install.sh --profile=server

Each profile has its own:

Brewfile with appropriate packages
Template files with environment-specific settings
Custom configurations for AI tools

For example, the work profile configures Goose to use OpenAI instead of Anthropic, which is useful in work environments where Anthropic access may not be available.

Available profiles:

personal: Full-featured setup with entertainment apps
work: Professional setup without entertainment apps
server: Minimal CLI-only setup for servers

🔄 Maintaining Your System

This repository includes tools for maintaining system integrity:

Changelog: System modifications are tracked in CHANGELOG.md
ADW for Maintenance: Use AI workflows for system updates and maintenance
Homebrew Manager: Run ./bin/brew-manager.sh to safely manage Homebrew taps and packages
Installation Analyzer: Run ./bin/install-analyzer.sh to get AI-powered analysis of installation issues
Context Documentation: Always update contexts/system.md after modifying the system to keep documentation in sync

Installation Analysis

The Installation Analyzer provides AI-powered diagnostics for your dotfiles installation:

# Run a fresh installation with AI analysis
./bin/install-analyzer.sh --verbose

# Analyze a specific profile installation
./bin/install-analyzer.sh --profile=minimal

# Choose between Goose and PydanticAI analysis engines
./bin/install-analyzer.sh --ai=goose
./bin/install-analyzer.sh --ai=pydantic

# Use the convenient wrapper script from anywhere
dotfiles-analyzer --quick --verbose

The analyzer will:

Run the installation process
Capture and analyze all output
Determine if there were any errors or warnings
Create a contextually relevant recovery plan
Save detailed logs for future reference

This is especially useful when setting up a new machine or updating to a new macOS version where compatibility issues might arise.

📝 Extending Your System

Each component can be extended and customized:

Profiles: Add new Brewfiles and templates for custom profiles
Packages: Modify package lists in packages/
Configuration: Add tool configs in config/
AI Workflows: Create new workflows in config/adw/

See the README in each directory for specific extension guidelines.

🔄 Updating

To update your dotfiles:

cd ~/Projects/dotfiles
git pull
./install.sh

# Or update with specific profile
./install.sh --profile=<profile_name>

📜 License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0) - see the LICENSE file for details.

This means you can freely share and adapt the code for non-commercial purposes, as long as you provide attribution to the original author.

🐍 Python Environment

The dotfiles configure Python with modern tools for a better development experience:

UV - A faster, more reliable Python package manager and installer:
- Replaces pip commands with UV alternatives
- Sets up proper dependency resolution
- Generates lockfiles for reproducible environments
pyenv - Manages Python versions

Python Features

Virtual environments: Create with create-venv [name]
Package management: Use UV commands with aliases like uvpip, uvinstall, etc.
Project scaffolding: Create project templates with scaffold --type mcp --path <path>

Configuration

UV settings can be customized in your ~/.zshrc.local file:

# Example custom UV configuration
export UV_VIRTUALENV_PYTHON="/usr/local/bin/python3.11"
export UV_EXTRA_INDEX_URL="https://my-custom-index/simple/"

🟩 Node.js Environment

The dotfiles configure Node.js with enhanced tools for better development:

NVM - Node Version Manager for switching between Node versions:
- Lazy-loaded for faster shell startup
- Automatic version switching using .nvmrc files
- Enhanced npx command that respects project Node versions
Project Management:
- create-node-project - Create a new Node project with proper setup

Node.js Features

Version Management: Auto-switching when changing directories with .nvmrc files
Smart npx: Uses the project's Node version based on .nvmrc or package.json

Project Initialization: Quick setup with various templates:

# Create a new basic Node.js project with LTS Node
create-node-project my-project

# Create a project with a specific Node version
create-node-project my-project 18.19.0

# Create a project with a specific template (basic, react, express, typescript)
create-node-project my-project lts typescript

Usage Examples

# Create a new project with the latest LTS Node
create-node-project my-project

# Create a project with a specific Node version
create-node-project my-project 18.19.0

# Use npx with the project's Node version (automatic)
cd my-project
npx some-package

Project Scaffolding

The system includes a scaffolding tool to quickly create new projects with best practices:

# Create a new MCP tool project
scaffold --type mcp --path ~/Projects

# Create other project types (more types coming soon)
scaffold --type <project-type> --path <destination-path>

The scaffold command is available in your PATH after installation, so you can use it from anywhere.

Available scaffold types:

mcp: Creates a new MCP tool project with FastMCP server setup

The scaffolding system is extensible - see scripts/scaffold-scripts/ for implementation details.

📂 Quick Directory Access

The dotfiles include a convenient command o to quickly open key directories in Finder. This command supports tab completion for ease of use.

Usage

# Open the Projects directory
$ o projects

# Open the Downloads directory
$ o downloads

# Open the Desktop directory
$ o desktop

# Open the Documents directory
$ o documents

This feature allows you to quickly navigate to frequently used directories directly from the terminal, enhancing your workflow efficiency. 🎉

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
bin		bin
config		config
contexts		contexts
examples		examples
packages		packages
scripts		scripts
tests		tests
.current_profile		.current_profile
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh

License

dylan-isaac/dotfiles

Folders and files

Latest commit

History

Repository files navigation