Codebase Summary

Duc’s Digital Workspace: AI-native macOS development environment with 35 dotfiles packages managed via GNU Stow.

Structure Overview

Core Packages (35 total)

Editors & IDEs:

• nvim - Neovim with AstroNvim v6 distribution
• nvim-vscode - VSCode Neovim integration
• vscode - VSCode settings and keybindings

Terminal & Shell:

• zsh - Primary shell configuration with Oh My Zsh
• herdr - Primary terminal workspace manager for coding agents
• tmux - Legacy terminal multiplexer with custom plugins
• ghostty - Modern terminal emulator
• kitty - Alternative terminal emulator
• atuin - Intelligent shell history with sync
• starship - Cross-shell prompt configuration

Window Management:

• yabai - Tiling window manager (BSP layout)
• skhd - Hotkey daemon for app switching
• karabiner - Keyboard customization
• hammerspoon - macOS automation scripts

File & Git Management:

• yazi - File manager with custom plugins
• lazygit - Git TUI configuration
• bin - Custom workspace, file-opening, and automation scripts

Development Tools:

• direnv - Automatic environment loading
• mise - Runtime version management
• task - Task runner configuration
• zathura - PDF viewer configuration

Other:

• claude - Claude AI user configuration
• vrapperrc - Vim keybindings for Eclipse

Scripts (13 scripts)

Installation & Setup:

• scripts/macos-deps.sh - Install macOS dependencies
• scripts/ci/ - CI pipeline scripts (validate, check-dependencies, test-platforms)

Neovim Management:

• scripts/nvim-install-parser.sh - Install treesitter parsers
• scripts/nvim-treesitter-arm64.sh - ARM64 specific setup
• scripts/refresh-nvim.sh - Refresh Neovim plugins

Maintenance:

• scripts/yabai-upgrade.sh - Update window manager
• scripts/export-atuin-aliases.sh - Export shell aliases
• scripts/import-atuin-aliases.sh - Import shell aliases
• scripts/appscript-notifications.scpt - macOS notifications

Configuration Files

• Makefile - Build automation (stow install/clean, alias management)
• .stow-local-ignore - GNU Stow ignore patterns
• .repomixignore - Repomix packing exclusions
• .gitleaksignore - Secrets scanning exclusions
• .gitignore - Git ignore patterns
• zensical.toml - Documentation site configuration
• mise.toml - Runtime version specifications
• CLAUDE.md - Claude AI project instructions

Documentation

• docs/ - Main documentation folder with guides for all tools
• dotfiles/nvim/.config/nvim/docs/ - Neovim-specific AI documentation

Key Features

Window Management

• Yabai - Binary space partitioning with 5px gaps
• SKHD - Modal hotkey system with app shortcuts
• App Rules - Specific window behavior per application

AI Integration

• Supermaven - Real-time code completion (Tab to accept)
• CodeCompanion - Gemini API chat and inline assistance
• Database AI - SQL-specific AI helpers via miudb
• fzf-lua - Fuzzy finder (replaced Telescope)
• Oil.nvim - File explorer (replaced Neo-tree)

Terminal Workflows

• Herdr - Persistent workspaces, panes, and agent navigation
• Tmux - Legacy session management with custom plugins
• Atuin - Command history with cloud sync
• Starship - Modern shell prompt with themes
• Ghostty - Primary terminal with modern features

Development Environment

• AstroNvim - Modern Neovim distribution
• Language Servers - LSP support for multiple languages
• Database Tools - Advanced SQL with Snowflake support
• Version Management - Mise for runtime versions

Dependencies

System:

• macOS 12.0+
• Homebrew
• Git
• GNU Stow

Installed via Scripts:

• Neovim + plugins
• Herdr via mise
• Tmux + TPM (legacy)
• Terminal emulators (Ghostty, Kitty)
• Development tools (Node, Python, Rust)
• Window managers (Yabai, SKHD)

Maintenance

Key Files for Updates:

• Makefile - Installation procedures
• README.md - Public documentation
• CLAUDE.md - Development instructions
• dotfiles/nvim/ - Editor configuration
• dotfiles/zsh/.zshrc - Shell setup

Common Tasks:

• Stow install/clean: make stow-install/clean
• Alias management: make export/import-aliases
• Service restart: brew services restart yabai skhd
• Config reload: herdr server reload-config
• Plugin updates: :Lazy sync (Neovim), prefix + I (legacy Tmux)

Documentation Hierarchy

1. Installation - Setup from scratch
2. Quick Reference - Essential commands
3. Tool Guides - Detailed configuration (Herdr, Neovim, SKHD, Atuin, and legacy Tmux)
4. Troubleshooting - Common issues and fixes
5. AI Workflows - Best practices for AI tools
6. Advanced - Custom configurations and extensions