Installation
Get started with DotClaude in minutes with our safety-first approach.
Contributor shell (optional)
The repository has an optional devenv shell for working on the repository on macOS or Linux. Install only its prerequisites, then enter it and run the named checks:
./scripts/install.sh --contributor
devenv shell
devenv tasks run ci:lint
devenv tasks run ci:all # full release/scheduled-CI check; devenv test is equivalent
devenv tasks run local:docs # optional modified-file-filtered local shortcutCodex cloud environment
For a Codex cloud setup script, select Manual and paste the same bootstrap command:
./scripts/install.sh --contributorLeave container caching enabled. The installer realizes the locked shell during the network-enabled setup phase, making its binaries available from the cached Nix store without running any DotClaude deployment step. In Codex cloud it adds launchers for Nix and devenv to the default agent PATH, which persists across the separate setup, maintenance, and agent Bash sessions.
Use the same idempotent command for the Maintenance script:
set -euo pipefail
./scripts/install.sh --contributorDo not start maintenance with a bare command -v devenv: older cached images can have Nix installed while its profile is absent from that session's PATH. Reset the container cache once after saving these settings.
The locked shell contains only contributor tools: Bun, Python, Git, ShellCheck, and shfmt. Shell entry has no setup hook: it does not invoke Stow, Homebrew, apt, font installation, macOS defaults, or any repository install script, and therefore does not create, remove, or replace user configuration under $HOME. Only an explicit host-install command from the sections below changes the host.
devenv is not required. Contributors with the native dependencies can run the same repository-only checks through the Makefile:
make ciThe contributor shell validates repository sources; the installer below deploys dotfiles and manages the host. Keeping that boundary explicit makes opening a development shell safe on both supported operating systems.
Prerequisites
- macOS (tested on macOS Sonoma 14.5+)
- Basic terminal familiarity
That's it! The installer handles everything else (Homebrew, Git, Xcode CLI tools).
Quick Installation (Fresh Mac)
For a brand new Mac without SSH keys configured:
# One-liner bootstrap - works without SSH keys
curl -fsSL bootstrap.kormie.link | bashInstall Options
# Full installation (default) - all features
curl -fsSL bootstrap.kormie.link | bash
# Minimal installation - core only
curl -fsSL bootstrap.kormie.link | INSTALL_MODE=minimal bash
# Interactive installation - choose components
curl -fsSL bootstrap.kormie.link | INSTALL_MODE=interactive bashInstallation (With SSH Keys)
If you already have SSH keys configured with GitHub:
# Clone and install
git clone git@github.com:kormie/dotclaude.git ~/.dotfiles
cd ~/.dotfiles
./scripts/install.sh --allInstallation (HTTPS)
# Clone via HTTPS
git clone https://github.com/kormie/dotclaude.git ~/.dotfiles
cd ~/.dotfiles
./scripts/install.sh --allWhat Gets Installed
The setup script installs modern CLI tools that coexist with your existing setup:
| Tool | Purpose | Alias | Original |
|---|---|---|---|
| exa/eza | Enhanced ls | ll2 | ls |
| bat | Syntax highlighting cat | cat2 | cat |
| fd | Fast find alternative | find2 | find |
| ripgrep | Ultra-fast grep | grep2 | grep |
| delta | Better git diffs | (git integration) | - |
| difftastic | Syntax-aware diffs | git dtl | - |
| zoxide | Smart directory navigation | z | cd |
Safety Features
Your existing setup remains completely untouched:
- ✅ All existing dotfiles are automatically backed up
- ✅ New tools use different command names (with
2suffix) - ✅ Original commands continue to work exactly as before
- ✅ Easy rollback if you want to remove anything
Next Steps
- Quick Setup - Apply your first configurations
- Safety Guide - Understand the backup/restore system
- Linux Server Setup (Minimal Profile) - VPS bootstrap (tmux + vim-min + mosh + fzf/bat/zoxide)
- Modern Tools - Learn about the new CLI tools
Verification
Verify your installation is working:
# Check tool availability
ll2 # Should show enhanced directory listing
cat2 --help # Should show bat help with syntax highlighting info
git lg # Should show your preferred git log format
# Test Claude Code workspace (if claude-code is installed)
cw test-project feature-1 feature-2 # 'cw' is an alias for 'tmux-claude-workspace'Troubleshooting
Command not found errors?
# Reload your shell configuration
source ~/.zshrc
# or
exec $SHELLNeed to rollback?
# Restore from automatic backup
./scripts/restore.shStill having issues? Check our troubleshooting guide or open an issue.
What's Next?
Once installation is complete, you're ready to: