Dotfiles

Version-controlled terminal and application configurations for consistent development environment across machines.

Overview

This repository contains my personal dotfiles, primarily focused on Alacritty terminal configuration optimized for:

• Claude/Codex CLI interactive sessions
• WSL Ubuntu with zsh
• High-performance terminal rendering (RTX 5090 optimized)
• Multi-line input support with proper keybindings

Why Version Control Dotfiles?

• History & Rollback: Revert breaking changes easily
• Synchronization: Share configs across Windows/macOS/Linux machines
• Auditable Changes: Clear commit history of what changed and why
• Safe Experimentation: Use branches to test new configurations
• Backup & Recovery: Never lose your carefully tuned configs
• Reproducible Setup: Quick setup on new machines

Repository Structure

dotfiles/
├── alacritty/
│   ├── alacritty.toml           # Main Alacritty config with modular imports
│   ├── themes/
│   │   ├── fonts.toml           # Font configuration (FiraCode Nerd Font)
│   │   ├── colors.toml          # Color scheme (Tokyo Night)
│   │   └── keybindings.toml     # Keybindings (Claude/Codex optimized)
│   └── fallback/
│       ├── alacritty-minimal.toml      # Minimal fallback config
│       └── alacritty-powershell.toml   # PowerShell variant
├── scripts/
│   ├── install.ps1              # Windows installation script
│   └── uninstall.ps1            # Windows uninstallation script
├── .gitignore
└── README.md

Installation

Windows (Primary)

Requirements:

• PowerShell with Administrator privileges
• Git installed and configured
• Alacritty installed

Steps:

1. Clone this repository:

   cd ~
   git clone https://github.com/alterspective-io/dotfiles.git
   cd dotfiles

2. Run the installation script:

   # Open PowerShell as Administrator
   .\scripts\install.ps1

   This script will:

   • Create junctions/symlinks from %APPDATA%\alacritty to your dotfiles
   • Back up any existing configurations automatically
   • Set up the modular config structure

3. Restart Alacritty to load the new configuration

macOS / Linux

Note: While this repo is currently Windows-focused, you can adapt it for Unix systems:

cd ~
git clone https://github.com/alterspective-io/dotfiles.git
cd dotfiles

# Create symlinks manually or adapt the PowerShell script
mkdir -p ~/.config/alacritty
ln -sf "$(pwd)/alacritty/alacritty.toml" ~/.config/alacritty/alacritty.toml
ln -sf "$(pwd)/alacritty/themes" ~/.config/alacritty/themes

Configuration Highlights

Alacritty Features

• Modular Configuration: Separated into fonts, colors, and keybindings for easy customization
• WSL Integration: Launches Ubuntu WSL with zsh by default
• Claude/Codex Optimized:
  • Shift+Enter for multi-line input (newline without submit)
  • Enter for normal submit
  • Proper raw mode support for TUI applications
• Clipboard Integration: OSC 52 support for WSL → Windows clipboard
• Performance Tuned: 10k line scrollback, GPU-accelerated rendering
• Visual Customization: Tokyo Night color scheme, FiraCode Nerd Font with ligatures

Key Bindings (Partial List)

Keybinding	Action
Shift+Enter	Insert newline (multi-line input)
Ctrl+Shift+C	Copy
Ctrl+Shift+V	Paste
Ctrl+Plus/Minus	Increase/Decrease font size
Ctrl+Shift+F	Search forward
F11	Toggle fullscreen

See alacritty/themes/keybindings.toml for complete list.

Making Changes

Workflow

1. Edit configs in the dotfiles repository:

   cd ~/dotfiles/alacritty/themes
   # Edit fonts.toml, colors.toml, or keybindings.toml

2. Test immediately: Alacritty auto-reloads config (live_config_reload = true)

3. Commit changes:

   cd ~/dotfiles
   git add .
   git commit -m "Update keybindings: fix Shift+Enter for Claude CLI"
   git push

4. Sync to other machines:

   cd ~/dotfiles
   git pull
   # Config automatically updates (if using symlinks/junctions)

Branching for Experiments

cd ~/dotfiles
git checkout -b experiment-new-colorscheme

# Make changes
# Test thoroughly

# If good, merge:
git checkout main
git merge experiment-new-colorscheme

# If bad, abandon:
git checkout main
git branch -D experiment-new-colorscheme

Fallback / Safe Mode

If you make a breaking change, use the minimal fallback config:

alacritty --config-file ~\dotfiles\alacritty\fallback\alacritty-minimal.toml

This uses:

• Simple high-contrast colors
• Built-in Consolas font (no dependencies)
• Minimal keybindings
• No transparency
• No advanced features

Uninstallation

To remove the symlinks/junctions and revert to local configs:

# Open PowerShell as Administrator
cd ~\dotfiles
.\scripts\uninstall.ps1

This will remove the links and notify you about any backup files.

Troubleshooting

Symlink/Junction Issues on Windows

• Symptom: Config not loading, or "file not found" errors
• Solution:
  • Ensure you ran install.ps1 as Administrator
  • Check if junctions exist: Get-Item $env:APPDATA\alacritty\alacritty.toml | Select-Object *
  • Try using the fallback config to verify Alacritty works

Import Paths Not Resolving

• Symptom: Alacritty warns about unused/missing imports
• Check: The main alacritty.toml uses relative paths (themes/fonts.toml)
• Verify: The themes/ junction exists in %APPDATA%\alacritty\

Live Reload Not Working

• Check: live_config_reload = true in alacritty.toml
• Note: Some changes (like font family) may require a full Alacritty restart

WSL Integration Issues

• Symptom: Alacritty opens but WSL doesn't launch
• Check:
  • WSL Ubuntu is installed: wsl -l -v
  • The shell path in alacritty.toml is correct: program = "wsl.exe"

Contributing to This Repo

This is a personal dotfiles repo, but if you're collaborating or syncing across your own machines:

1. Pull before editing: Always git pull before making changes on a new machine
2. Descriptive commits: Explain why you changed a setting, not just what
3. Test before pushing: Ensure the config works before sharing to other machines
4. Tag stable versions: Use git tag v1.0-stable to mark known-good configs

OS-Specific Configs

Currently, this repo uses a single alacritty.toml optimized for Windows + WSL. To support multiple OSes:

Option 1: Conditional Imports (recommended)

import = [
    "themes/base.toml",
    "themes/windows.toml",  # Only exists on Windows machine
    "themes/macos.toml",    # Only exists on macOS machine
]

Alacritty ignores missing import files.

Option 2: Separate Branches

• main branch: Windows config
• macos branch: macOS config
• Pull the appropriate branch on each machine

License

This is a personal configuration repository. Feel free to fork and adapt for your own use.

Changelog

See Git commit history for detailed changes. Major milestones:

• 2025-10-18: Initial version with Alacritty config, modular structure, Windows install scripts

Resources

• Alacritty Documentation
• Alacritty GitHub
• Managing Dotfiles with Git
• Nerd Fonts
• Claude Code Documentation

---

Maintained by: alterspective-io Primary System: Windows 11 Business N | Intel Core Ultra 9 285K | RTX 5090 Last Updated: 2025-10-18