nix/README.md

Personal Nix Configuration

A comprehensive Nix configuration for macOS using nix-darwin and home-manager, featuring a modern development environment with vim-centric workflows and beautiful aesthetics. Largely generated and maintained with Claude Code.

✨ Features

• 🎨 Beautiful UI: Gruvbox dark theme across all applications
• ⌨️ Vim-centric: Consistent vim keybindings throughout the stack
• 🚀 Modern CLI: Enhanced tools with fuzzy finding, syntax highlighting, and smart completion
• 📦 Modular Design: Separate configuration files for easy maintenance
• 🔄 Portable: Reproducible across machines with a single command

🚀 Quick Install

Install directly from GitHub without cloning:

# Darwin system configuration
sudo darwin-rebuild switch --flake github:Logan-Lin/nix-config

# Home Manager configuration  
home-manager switch --flake github:Logan-Lin/nix-config#yanlin

📁 Configuration Architecture

.
├── flake.nix          # Main flake configuration and package definitions
├── tmux.sh            # Tmux session automation script
├── modules/           # Nix configuration modules
│   ├── git.nix        # Git configuration with aliases and settings
│   ├── nvim.nix       # Neovim configuration with plugins and keymaps
│   ├── ssh.nix        # SSH client configuration and host management
│   ├── tmux.nix       # Tmux setup with vim-like navigation
│   └── zsh.nix        # Zsh with Powerlevel10k and modern CLI tools
├── config/            # Configuration files
│   ├── p10k.zsh       # Powerlevel10k theme configuration
│   └── projects.nix   # Project shortcuts configuration
└── scripts/           # Utility scripts
    ├── project-launcher.sh  # Universal project launcher
    └── templates/     # Tmux session templates
        ├── basic.sh   # Basic development template
        ├── content.sh # Content workflow template
        └── research.sh # Research workflow template

🛠️ Software Configurations

📝 Neovim

Theme: Gruvbox dark with hard contrast Leader Key: <Space>

Key Features:

• File Explorer: nvim-tree with dotfile filtering
• Syntax Highlighting: Treesitter with all grammar support
• Git Integration: vim-fugitive for git operations
• Status Line: lualine with gruvbox theme and relative paths
• System Clipboard: Seamless integration for copy/paste
• Markdown Rendering: render-markdown.nvim for beautiful in-buffer markdown preview

Keybindings:

Key	Mode	Action
<Space>e	Normal	Toggle file explorer
<Space>w	Normal	Save file
<Space>q	Normal	Quit
<Space>o	Normal	Open file with system default app
<Space>f	Normal	Show current file in Finder
<Space>y	Normal/Visual	Copy to system clipboard
<Space>p	Normal/Visual	Paste from system clipboard
<Space>gs	Normal	Git status
<Space>gd	Normal	Git diff
<Space>gc	Normal	Git commit
<Space>gp	Normal	Git push
<Space>md	Normal	Toggle markdown rendering

🖥️ Tmux

Prefix Key: Ctrl+a (instead of default Ctrl+b) Theme: Gruvbox dark with visual prefix indicator

Key Features:

• Prefix Indicator: Shows <Prefix> in status bar when prefix is active
• Vim-like Navigation: hjkl for pane movement
• Smart Splitting: Maintains current directory when creating panes
• Copy Mode: System clipboard integration with pbcopy

Keybindings:

Key	Action
Ctrl+a	Prefix key
Ctrl+a |	Split window vertically
Ctrl+a -	Split window horizontally
Ctrl+a h/j/k/l	Navigate panes (vim-style)
Ctrl+a H/J/K/L	Resize panes
Ctrl+a r	Reload tmux config
Ctrl+a Ctrl+a	Quick pane cycling

Copy Mode (Ctrl+a [):

Key	Action
v	Begin selection
y	Copy selection to system clipboard
r	Toggle rectangle selection

🌟 Git Configuration

Configuration: modules/git.nix Purpose: Declarative git configuration with user info, aliases, and sensible defaults

Key Features:

• User Identity: Name and email managed declaratively
• SSH Integration: Disabled credential helper to use SSH keys
• Comprehensive Aliases: Shortcuts for common git operations
• Sensible Defaults: Cross-platform compatible settings

Complete Aliases Reference:

Alias	Command	Description
git st	status	Show working tree status
git co	checkout	Switch branches or restore files
git br	branch	List, create, or delete branches
git ci	commit	Record changes to repository
git cm "msg"	commit -m	Quick commit with message
git ca	commit --amend	Amend the last commit
git up	pull --rebase	Pull and rebase (cleaner history)
git d	diff	Show unstaged changes
git dc	diff --cached	Show staged changes
git ds	diff --stat	Show diff statistics
git lg	log --color --graph...	Beautiful colored log with graph
git lga	log --color --graph... --all	Same as lg but all branches
git last	log -1 HEAD	Show the last commit
git sl	stash list	List all stashes
git sp	stash pop	Apply and remove latest stash
git ss	stash save	Save current changes to stash
git unstage	reset HEAD --	Remove files from staging area
git visual	!gitk	Launch gitk GUI

Configuration Management:

Edit git settings in modules/git.nix, then apply:

home-manager switch --flake .#yanlin

Benefits:

• ✅ Reproducible: Same git config across all machines
• ✅ Version Controlled: Git settings tracked with other configurations
• ✅ SSH Integration: Works seamlessly with SSH module
• ✅ Override Defaults: Properly disables nix's default credential helper

🔐 SSH Configuration

Configuration: modules/ssh.nix Purpose: Declarative SSH client configuration and host management

Key Features:

• Declarative Hosts: All SSH hosts defined in nix configuration
• Version Controlled: SSH config tracked with git alongside other configurations
• Reproducible: Same SSH setup deployable across multiple machines
• Security: Private keys remain local and untracked

Host Management:

Edit SSH hosts in modules/ssh.nix, then apply changes:

home-manager switch --flake .#yanlin

Configured Hosts:

• aicloud: Development server via proxy jump
• nas: Network storage server
• pi: Raspberry Pi home server
• cm: Compute module
• personal-vps: Cloud VPS instance
• zero: Pi Zero device
• ucloud-a40: A40 GPU cluster
• ucloud-h100: H100 GPU cluster

Security Best Practices:

• ✅ SSH configuration: Managed by nix (hosts, ports, usernames)
• ❌ Private keys: Keep local in ~/.ssh/keys/ (not tracked by nix)
• ❌ known_hosts: Generated locally (not synced)

Important: Only the SSH client configuration is managed by nix. Private keys and sensitive data remain local and secure.

🐚 Zsh with Powerlevel10k

Theme: Powerlevel10k lean style with 2-line prompt Vim Mode: Enabled with visual indicators

Key Features:

• Smart Completion: Case-insensitive with menu selection
• Autosuggestions: Fish-like command suggestions
• Syntax Highlighting: Real-time command syntax highlighting
• History Management: Shared history with deduplication
• Vim Mode Indicators: Cursor shape changes and prompt symbols

Vim Mode Indicators:

• Insert Mode: Line cursor | + ❯ prompt (green)
• Normal Mode: Block cursor █ + ❮ prompt
• Fast Switching: 10ms escape timeout for responsive mode changes

Vim Mode Keybindings:

Key	Mode	Action
Esc	Insert	Switch to normal mode
i/a/I/A	Normal	Switch to insert mode
k/j	Normal	History search backward/forward
/	Normal	History incremental search backward
?	Normal	History incremental search forward
Ctrl+Right/Left	Insert	Word movement

Aliases:

Navigation:

l, ll, la          # Enhanced ls commands
.., ..., ....      # Quick directory navigation
home, config       # Jump to common directories
nix-config         # Jump to nix configuration

Git:

g, gs, ga, gc, gp, gl, gd, gco, gb  # Git shortcuts
glog               # Beautiful git log with graph

Modern CLI:

cat → bat          # Syntax highlighted file viewing
find → fd          # Fast file finding
grep → rg          # Ripgrep for fast searching
top → btop         # Beautiful system monitor

Nix:

hm                 # home-manager shortcut
hms                # Quick home-manager switch

🚀 Project Shortcuts

Configuration: config/projects.nix Purpose: Quick access to project workspaces with tmux sessions

Example Projects:

• blog: Personal blog with code + content workflow
• nix-config: Nix configuration with basic development workflow

Usage:

proj              # List all available projects
blog              # Launch blog project tmux session
nix-config        # Launch nix-config project tmux session

Template Types:

• Basic: Single directory (nvim + ai + git + shell)
• Content: Code directory + separate content directory
• Research: Code directory + separate paper directory + optional remote server

Research Template Remote Server Support:

The research template supports optional remote server connections with these features:

• Remote Server Window: Window 7 with dual horizontal panes for parallel remote work
• Automatic Connection: SSH to configured server with automatic directory navigation
• Reconnect Alias: Type r in any remote pane to easily reconnect after network drops
• Configuration: Add server and remoteDir fields to research projects

Example Configuration:

mdshortcut = {
  template = "research";
  # ... other fields ...
  server = "aicloud";      # SSH host from ~/.ssh/config
  remoteDir = "~/MDS";     # Remote directory path
};

Adding New Projects:

Edit config/projects.nix and run hms to rebuild configuration.

🌟 Git Visualization

Tool: lazygit Purpose: Simple terminal UI for git commands with intuitive interface

Launch with lazygit in any git repository for:

• Interactive commit graph and branch visualization
• Streamlined staging, committing, and diff viewing
• Easy branch management and merging
• File tree navigation with git status
• Intuitive keyboard shortcuts and help system

🌟 Code Editing & Auto-completion

Tool: Neovim with NixVim Purpose: Modern text editor with declarative configuration and basic auto-completion

Configured with essential plugins and basic auto-completion for improved productivity:

Key Features:

• Gruvbox theme: Dark theme with hard contrast for better readability
• Tree-sitter: Advanced syntax highlighting for multiple languages
• File explorer: nvim-tree for project navigation
• Auto-completion: Basic word and path completion without language servers
• Git integration: vim-fugitive for version control operations
• Markdown rendering: Live preview for documentation

Auto-completion Usage:

Basic completion:

Ctrl+Space    # Trigger completion menu manually
Tab           # Navigate to next completion item
Shift+Tab     # Navigate to previous completion item
Enter         # Accept selected completion
Ctrl+e        # Close completion menu

Completion sources:

• Buffer completion: Suggests words from currently open files
• Path completion: Suggests file and directory paths when typing paths

Essential Keybindings:

File operations:

<leader>e     # Toggle file explorer (nvim-tree)
<leader>w     # Save current file
<leader>q     # Quit current buffer
<leader>o     # Open file with system default app
<leader>f     # Show current file in Finder

System clipboard:

<leader>y     # Copy selection to system clipboard
<leader>p     # Paste from system clipboard

Git operations:

<leader>gs    # Git status
<leader>gd    # Git diff
<leader>gc    # Git commit
<leader>gp    # Git push

Note: Leader key is set to spacebar. Basic auto-completion provides word suggestions from open files and path completion without requiring language server setup.

🌟 File Synchronization & Backup

Tool: rsync Purpose: Declarative file synchronization and backup management

Configured with comprehensive exclude patterns and backup presets:

Configuration Files:

• ~/.rsync-exclude - Common exclude patterns (macOS metadata, temp files)
• ~/.rsync-backup.conf - Standard backup options with safety features
• ~/.local/bin/rsync-backup - Convenient backup wrapper script
• ~/.rsync-aliases - Shell aliases for common operations

Usage Examples:

Using the backup wrapper:

# Quick backup with progress and safety
rsync-backup ~/Documents/ /backup/documents/

# The script automatically applies exclude patterns and safety options

Using shell aliases (source ~/.rsync-aliases first):

rsync-quick source/ dest/     # Basic backup with progress
rsync-dry source/ dest/       # Dry run for testing (safe)
rsync-sync source/ dest/      # Sync without deleting files
rsync-mirror source/ dest/    # Mirror with delete (exact copy)

Manual rsync with config:

# Use the backup configuration file
rsync $(cat ~/.rsync-backup.conf | grep -v '^#' | tr '\n' ' ') source/ dest/

# Or with custom exclude patterns
rsync -avh --progress --exclude-from=~/.rsync-exclude source/ dest/

Features:

• Automatic exclusion of temporary files and macOS metadata
• Progress indication and compression for network transfers
• Safety options including partial transfers and dry-run capability
• Preserves extended attributes and ACLs on macOS

🌟 Reference Management

Tool: papis Purpose: Command-line reference manager for academic papers and documents

A powerful bibliography manager that stores documents and metadata in a human-readable format:

Key Features:

• Document Library: Centralized storage at ~/Documents/Library/papis
• BibTeX Integration: Import/export references in standard academic formats
• PDF Management: Automatic file organization and retrieval
• Search & Filter: Fast document discovery with fuzzy finding (fzf)
• Metadata Storage: Human-readable YAML files for bibliographic data
• Editor Integration: Configured with nvim for editing document metadata

Usage Examples:

Adding documents:

# Add a paper from DOI
papis add --from doi 10.1000/example.doi

# Add a PDF file with interactive metadata entry
papis add paper.pdf

# Add from arXiv
papis add --from arxiv 2301.12345

# Add from URL
papis add --from url https://example.com/paper.pdf

Searching and browsing:

# List/search documents
papis list
papis list "machine learning" 
papis list author:smith year:2023

# Open documents (uses fzf picker)
papis open
papis open bohm

# Open document folder
papis open -d einstein

Document management:

# Edit document metadata
papis edit bohm

# Export to BibTeX
papis export --all --format bibtex > references.bib
papis export --format bibtex query_term > references.bib

# List documents with custom format
papis list --format '{doc[author]} - {doc[title]} ({doc[year]})'

Workflow Aliases:

# Bibliography formatting
papis-bib                    # List documents with formatted template
papis-bib "machine learning" # Search and format specific documents

# File operations  
papis-add-file filename.pdf [query]  # Add file from ~/Downloads/ to existing entry
papis-add-url [url] [query]          # Add file from URL to existing entry

# Directory access
papis-finder [query]                 # Open document directory in Finder

Configuration location: modules/papis.nix with embedded configuration Main library: ~/Documents/Library/papis Editor: nvim (configured automatically) Picker: fzf for interactive document selection

🌟 Python Development & Package Management

Tool: uv Purpose: Extremely fast Python package installer and resolver, written in Rust

A modern replacement for pip, virtualenv, pip-tools, and more - providing 10-100x faster performance:

Key Features:

• Unified toolchain: Single tool replaces pip, virtualenv, pip-tools, poetry, and more
• High performance: 10-100x faster than pip with global caching and Rust implementation
• Drop-in compatibility: Works with existing requirements.txt files and PyPI packages
• Modern dependency resolution: Better handling of complex dependency trees
• Virtual environment management: Automatic venv creation and management

Usage Examples:

Project initialization and management:

# Create a new Python project
uv init my-project
cd my-project

# Add dependencies (creates/updates pyproject.toml)
uv add requests pandas numpy

# Add development dependencies
uv add --dev pytest black isort

# Install dependencies from requirements.txt or pyproject.toml
uv sync

Virtual environment management:

# Create virtual environment (automatic when needed)
uv venv

# Activate virtual environment
source .venv/bin/activate

# Install packages in virtual environment
uv pip install package-name

# Run commands in virtual environment context
uv run python script.py
uv run pytest

Package installation and management:

# Install packages (faster than pip)
uv pip install requests
uv pip install -r requirements.txt

# Upgrade packages
uv pip install --upgrade package-name

# Install specific versions
uv pip install "django>=4.0,<5.0"

Tool usage (like pipx):

# Install and run CLI tools
uv tool install black
uv tool run black --help

# Run tools without installing
uv tool run ruff check .

Migration from pip/virtualenv:

• Replace pip install with uv pip install for faster installs
• Replace python -m venv with uv venv for faster environment creation
• Use uv add instead of manually editing requirements.txt
• Use uv sync to install from lock files for reproducible environments

📦 Included Packages

Development Tools

• Python 3.12: With uv (modern Python package manager)
• LaTeX: Full TeXLive distribution
• Claude Code: AI-powered coding assistant
• Git UI: Beautiful git graph visualization

CLI Utilities

• fzf: Fuzzy finder for files, commands, and history
• fd: Fast, user-friendly alternative to find
• ripgrep (rg): Fast text search
• bat: Syntax-highlighted cat replacement
• btop: Modern system monitor
• httpie: Modern HTTP client for API testing
• lazysql: LazyGit-style TUI database management tool
• sqlite3: Official SQLite command-line interface
• lftp: Scriptable FTP client for automation
• termscp: Comprehensive TUI file transfer client (FTP/SFTP/SCP/S3)
• rsync: Fast file synchronization and backup with comprehensive configuration
• zoxide: Smart cd with frecency algorithm

fd Usage Examples

fd filename          # Find files/directories named "filename"
fd "*.nix"          # Find all Nix files
fd -t f config      # Only files (-t f = type file)
fd -t d config      # Only directories (-t d = type directory)
fd -e js            # All files with .js extension
fd -H hidden        # Include hidden files (-H)
fd | fzf            # Pipe to fzf for interactive selection

fzf Usage Examples

fzf                  # Interactive file finder
ls | fzf            # Fuzzy find from any list
history | fzf       # Search command history
fd | fzf            # Fast file finding with fuzzy selection
fd -t d | fzf       # Find and select directories only
rg "pattern" | fzf  # Search text then fuzzy filter results

# Preview files while browsing
fzf --preview 'bat --style=numbers --color=always {}'

Built-in zsh keybindings:

• Ctrl+T - Insert selected files/directories into command line
• Ctrl+R - Search command history interactively
• Alt+C - Change to selected directory

httpie Usage Examples

# Simple HTTP requests
http GET api.example.com/users
http POST api.example.com/users name="John" email="john@example.com"
http PUT api.example.com/users/1 name="Jane"
http DELETE api.example.com/users/1

# With authentication headers
http GET api.example.com/protected Authorization:"Bearer your-token"
http GET api.example.com/api X-API-Key:"your-api-key"

lazysql Usage Examples

# Launch TUI database management (LazyGit-style interface)
lazysql

# Connect to different databases
lazysql -h localhost -u username -p password -d database_name  # MySQL
lazysql --url postgres://user:pass@localhost/dbname           # PostgreSQL  
lazysql --url sqlite://./database.db                          # SQLite
lazysql --url "mysql://user:pass@localhost/db"                # MySQL URL format

# With config file (recommended for credentials)
lazysql --config ~/.config/lazysql/config.yml

# Interactive TUI operations:
# - Navigate tables with j/k (vim-style)
# - View table structure and data
# - Execute SQL queries in editor mode
# - Export query results
# - Browse database schema

Key lazysql features:

• LazyGit-inspired interface: Familiar navigation for developers
• Multi-database support: MySQL, PostgreSQL, SQLite
• SQL editor: Syntax highlighting and query execution
• Export capabilities: Save query results to files
• Connection management: Save and reuse database connections

sqlite3 Usage Examples

# Connect to SQLite database
sqlite3 ai.db

# One-liner queries (no interactive session)
sqlite3 ai.db "SELECT COUNT(*) FROM users;"
sqlite3 ai.db "SELECT * FROM users WHERE active = 1;"

# Common SQLite dot commands (inside sqlite3 shell)
.tables                    # List all tables
.schema                    # Show all table schemas
.schema users              # Show specific table schema
.mode csv                  # Set output format (csv, json, html, etc.)
.headers on                # Show column headers
.output results.csv        # Redirect output to file
.output stdout             # Reset output to terminal

# Import/Export operations
.backup backup.db          # Create database backup
.restore backup.db         # Restore from backup
.dump                      # Export entire database as SQL
.dump users               # Export specific table as SQL

# Execute SQL script file
.read script.sql          # Run SQL commands from file
sqlite3 ai.db < script.sql # Alternative: pipe script to sqlite3

# Database inspection
.dbinfo                   # Show database information
.indices table_name       # Show indexes for table
.exit                     # Exit sqlite3 shell

Key sqlite3 features:

• Universal compatibility: Works with any SQLite database
• Scriptable: Perfect for automation and batch operations
• Lightweight: Minimal overhead for quick queries
• Import/Export: Built-in CSV, JSON, and SQL dump capabilities
• Backup tools: Simple database backup and restore operations

termscp Usage Examples

# Launch TUI file transfer client
termscp
ftp                  # Alias for termscp

# Quick connections
termscp ftp://user@host.com
termscp sftp://user@host.com:2222
termscp scp://user@host.com

# Advanced features
termscp --config     # Configure settings and bookmarks
termscp --version    # Show version information

Key termscp features:

• Rich TUI: Interactive file browser with dual-pane view
• Multi-protocol: FTP, SFTP, SCP, S3, WebDAV support
• Bookmarks: Save frequently accessed servers
• File operations: Create, rename, delete, search, edit files
• Synchronization: Sync directories between local and remote
• Themes: Customizable interface themes

Powerful Tool Combinations

# Find and open file with nvim using interactive selection
nvim $(fd --type f | fzf)

# Find and edit Nix configuration files
nvim $(fd "*.nix" | fzf)

# Search text content and open matching file
nvim $(rg -l "search_term" | fzf)

# Preview files while selecting which one to edit
nvim $(fd --type f | fzf --preview 'bat --color=always {}')

# Find and edit files in specific directory
nvim $(fd --type f . ~/.config | fzf)

Fonts

• Nerd Fonts: FiraCode and JetBrains Mono with icon support

🔄 Usage & Workflow

Daily Workflow

1. Terminal: Beautiful zsh with vim mode and modern tools
2. Tmux: Session management with vim navigation
3. Neovim: Code editing with git integration
4. Git UI: Visual git operations and branch management

Environment Management

# Refresh shell environment after nix changes
exec zsh

# Update and rebuild configuration
nix flake update
sudo darwin-rebuild switch --flake .
home-manager switch --flake .#yanlin

# Quick home-manager rebuild
hms

Clipboard Integration

The configuration provides seamless clipboard integration:

• Neovim: <Space>y/p for system clipboard
• Tmux: Copy mode automatically uses system clipboard
• Terminal: Standard Cmd+C/V works everywhere

💻 Machine Configurations

• iMac: iMac configuration
• MacBook-Air: MacBook Air configuration

Both machines use the same base configuration with potential for machine-specific customizations.

Machine-specific Usage:

# For MacBook Air
sudo darwin-rebuild switch --flake .#MacBook-Air

# For iMac  
sudo darwin-rebuild switch --flake .#iMac