A comprehensive, modular collection of dotfiles and configuration files for modern macOS development environments, optimized for Apple Silicon with Tokyo Night theme and AI-powered workflows.
- Features
- Prerequisites
- Installation
- Directory Structure
- Tool Configurations
- AI Integration
- API Utilities
- 🚀 One-command installation for fresh macOS systems
- 🔄 Easy updates for existing installations
- 🛠️ Comprehensive development tooling with optimized configurations
- ⌨️ Modern terminal setup with Ghostty, ZSH, Starship, and more
- 🖥️ Efficient window management with Aerospace and Hammerspoon
- 🎨 Consistent Tokyo Night theme across all tools
- 🧠 AI-powered workflows with Claude, GPT, and Gemini integration
- 📡 API development utilities with OpenAPI tools and client generation
- 🔒 Secure and maintainable setup with XDG compliance
- 📊 TypeScript SDK for programmatic access to all functionality
- macOS (Apple Silicon)
- Git
- Curl
- Zsh
For a fresh macOS installation:
# Clone the repository
git clone https://github.com/yourusername/dotfiles.git ~/dotfiles
# Run the setup script
cd ~/dotfiles
./scripts/setup.shThis will:
- Check system requirements
- Create XDG base directories
- Symlink configuration files
- Install Homebrew and packages (optional)
- Configure macOS preferences (optional)
- Set up the Git conventional commits workflow
- Initialize AI integrations and tools
For updating an existing installation:
# Navigate to dotfiles directory
cd ~/dotfiles
# Pull latest changes
git pull
# Run the setup script to update symlinks
./scripts/setup.sh --update./scripts/setup.sh [options]
Options:
--no-brew Skip Homebrew installation and updates
--no-macos Skip macOS preferences configuration
--minimal Install only essential configurations
--update Update existing installation
--ai-only Only update AI-related configurations
--help Show this help messagedotfiles/
├── config/ # Configuration files (XDG_CONFIG_HOME)
│ ├── aerospace/ # Aerospace window manager
│ ├── ai/ # AI tools and integrations
│ │ ├── core/ # Core AI configuration
│ │ ├── prompts/ # Reusable prompt templates
│ │ ├── providers/ # Provider-specific configs
│ │ ├── tools/ # Tool integrations (Git, API, etc.)
│ │ └── utils/ # TypeScript and Bash utilities
│ ├── atuin/ # Shell history
│ ├── bat/ # Cat alternative
│ ├── ghostty/ # Terminal emulator
│ ├── git/ # Git configuration
│ ├── hammerspoon/ # macOS automation
│ ├── nvim/ # Neovim editor
│ ├── starship/ # Shell prompt
│ ├── vscode/ # VS Code editor
│ ├── yazi/ # Terminal file manager
│ ├── zellij/ # Terminal multiplexer
│ └── zsh/ # ZSH configuration
├── docs/ # Documentation
├── home/ # Nix-related
├── modules/ # Nix-related
├── scripts/ # Utility scripts
│ └── setup.sh # Installation script
├── api/ # API specifications and clients
│ ├── specs/ # OpenAPI specifications
│ ├── clients/ # Generated API clients
│ └── server/ # API server implementations
├── sdk/ # TypeScript SDK for dotfiles
├── CLAUDE.md # Claude Code instructions
├── SPECIFICATIONS.md # Detailed specifications
└── README.md # This file
| Tool | README | Description |
|---|---|---|
| Aerospace | README | Window manager with Tokyo Night theme |
| AI Tools | README | AI-powered workflows with Claude, GPT, etc. |
| API Tools | README | REST API utilities and OpenAPI tools |
| Atuin | README | Shell history with sync and search |
| Bat | README | Cat clone with syntax highlighting |
| Git | README | Version control with safe defaults |
| Ghostty | README | Modern GPU-accelerated terminal |
| Hammerspoon | README | macOS automation framework |
| Neovim | README | Text editor with LazyVim config |
| Starship | README | Cross-shell prompt with Tokyo Night theme |
| VS Code | README | Editor with optimized settings |
| Yazi | README | Terminal file manager with Neovim integration |
| Zellij | README | Terminal multiplexer with layouts |
| ZSH | README | Shell with aliases and functions |
This dotfiles repository includes comprehensive AI integration for development workflows, organized in a modular, composable architecture:
+-------------------------------------+
| AI Configuration System |
+-------------------------------------+
|
+--------------------------------------------+
| | |
+----------v---------+ +---------v--------+ +------v------+
| Core Components | | Provider Integrations | | Interfaces |
+--------------------+ +--------------------+ +--------------+
| | | | | |
| +----------------+ | | +----------------+ | | +----------+ |
| | Config | | | | Claude | | | | CLI | |
| +-------+--------+ | | +-------+--------+ | | +----+-----+ |
| | | | | | | | |
| +-------v--------+ | | +-------v--------+ | | +----v-----+ |
| | Types | | | | OpenAI | | | | TypeScript| |
| +-------+--------+ | | +-------+--------+ | | | Library | |
| | | | | | | +----------+ |
| +-------v--------+ | | +-------v--------+ | | |
| | Utils | | | | Anthropic | | | |
| +----------------+ | | +----------------+ | | |
+--------------------+ +--------------------+ +--------------+
- Core Configuration: Centralized configuration with provider abstraction
- Prompts System: Modular, reusable prompt templates
- Provider Support: Implementations for Claude, GPT, Gemini, and local models
- Tool Integrations: Git hooks, IDE plugins, and API utilities
- TypeScript SDK: Programmatic access to AI functionality
- Bash Utilities: Shell integration for AI commands
# Generate code with AI
just ai:code typescript "Create a function that sorts an array"
# Review code with AI
just ai:review path/to/file.js
# Generate commit messages
just ai:commit-msg
# Create API client from OpenAPI spec
just api:generate-client path/to/spec.yaml output-dirThe repository is configured with a comprehensive Conventional Commits workflow for creating structured, standardized commit messages:
# Stage files with fuzzy selection
gfa
# Create conventional commit with interactive wizard
gcz
# Bypass validation for work-in-progress
gczf
All commits follow the conventional format:
- Type: The change category (feat, fix, docs, etc.)
- Scope: Optional component affected (auth, api, etc.)
- Description: A concise description of the change
- Body: Optional longer explanation
- Footer: Optional references to issues, breaking changes
The configuration also includes AI-assisted git commit message generation:
# Generate a conventional commit message with AI
git ai-commit
# Use AI to analyze code and create a detailed message
just ai commit-msgFor detailed information, see:
The api namespace provides comprehensive tools for API development:
# Validate OpenAPI specification
just api:optic:validate spec.yaml
# Start an API proxy for testing
just api:optic:proxy spec.yaml 8080
# Lint OpenAPI specification with Spectral
just api:spectral:lint spec.yaml
# Generate a TypeScript client
just api:generate-client spec.yaml ./clients/typescript
# Generate a Python client
just api:generate-python-client spec.yaml ./clients/python
# Start a mock server based on specification
just api:mock spec.yaml 8080# Make GET/POST/PUT/DELETE requests
just api:httpie:get https://api.example.com/users
just api:httpie:post https://api.example.com/users name=John age=30
# Save request to Bruno file for API collections
just api:httpie:save-to-bruno https://api.example.com/users GET example ./bruno/For detailed information, see the API Tools README.