Dotfiles

Configuration files for CLI tools and development environments on Linux and macOS, managed with GNU Stow.

Quick Start

Full install (recommended)

# Install prerequisites
# macOS:
brew install stow just
# Arch:
sudo pacman -S stow just
# Fedora:
sudo dnf install stow just
# Debian:
sudo apt-get install stow just

mkdir $HOME/Workspace
git clone <repo-url> $HOME/Workspace/dotfiles
cd $HOME/Workspace/dotfiles

# One command: installs packages, stows configs, clones plugins, sets up themes
just install

This auto-detects your OS and runs the appropriate package manager, then stows all configs, clones ZSH plugins and personal tools, installs TPM, the yazi theme, and imports shell history into atuin.

Manual / step-by-step

just pacman-install        # or apt-install / dnf-install / brew-install
just font-install
just stow-all              # symlink all configs
just zsh-plugins           # clone ZSH plugins
just tools-clone           # clone personal shell tools (~/Workspace/tools)
just tpm-install           # clone tmux plugin manager
just set-shell             # change default shell to zsh
just yazi-theme            # install yazi Catppuccin theme
just atuin-import          # import shell history into atuin
just check                 # verify core tools are installed

After install, open tmux and press prefix + I to install tmux plugins, then exec zsh to reload your shell.

Stow individual configs

just stow nvim
just stow zsh
just terminal=ghostty stow-all   # override default terminal

Task Runner

A justfile automates common operations:

Command	Description
just install	Full setup — packages, stow, plugins, themes (auto-detects OS)
just stow-all	Stow all configs (uses default terminal)
just unstow-all	Remove all symlinks
just restow-all	Re-stow all (after adding new files)
just stow <name>	Stow a single config
just unstow <name>	Unstow a single config
just font-install	Install JetBrainsMono Nerd Font (auto-detects OS)
just brew-install	Install macOS deps via Brewfile
just apt-install	Install core deps (Debian)
just pacman-install	Install core deps (Arch)
just dnf-install	Install core deps (Fedora); per-package dnf, pipx thefuck, prebuilt yazi
just tfswitch-install	Install Terraform version manager (replaces distro terraform package)
just zsh-plugins	Clone ZSH plugins (skips existing)
just tools-clone	Clone personal tools to ~/Workspace/tools
just tpm-install	Clone TPM for tmux (skips if exists)
just set-shell	Set default shell to zsh (no-op if already zsh)
just yazi-theme	Install yazi Catppuccin theme
just atuin-import	Import shell history into atuin
just check	Verify all core tools are installed

Override the default terminal emulator with just terminal=ghostty <command>.

Configurations

Shell & Prompt

Config	Description
zsh	Cross-platform ZSH config with OS detection, fzf, atuin history, zoxide, completions, SSH key auto-loading
starship	Custom "Dusk" prompt theme — muted pastel powerline with Catppuccin-inspired palette

Terminal Emulators

One terminal is stowed by default (configurable via just terminal=<name>).

Config	Description
kitty	GPU-accelerated terminal with Catppuccin Mocha colors, powerline tabs, transparency (optional; default is ghostty)
wezterm	Lua-configurable terminal with built-in multiplexing, WebGPU rendering, integrated titlebar (optional; default is ghostty)
ghostty	Native-rendering terminal by Mitchell Hashimoto, minimal config, background blur

All three use JetBrainsMono Nerd Font and Catppuccin Mocha theme.

Editor

Config	Description
nvim	Modern Neovim in Lua — Lazy.nvim, Mason, LSP, Treesitter, Copilot, conform + nvim-lint
vim	Legacy Vim config with Vundle (Neovim preferred)

Git

Config	Description
gitconfig	Histogram diffs, delta integration, 20+ aliases, auto-upstream, SSH auth

Requires git-delta. Create credentials at ~/.config/git/config.local.

Terminal Multiplexer

Config	Description
tmux	Prefix Ctrl+Space, vim-aware pane nav, Catppuccin theme, resurrect + continuum
tmux-tools	tmuxz and tmuxf — create/attach sessions via zoxide + fzf

TUI Tools

Config	Description
lazygit	Git TUI with Catppuccin Mocha theme, delta pager, Nerd Font icons
yazi	Terminal file manager with Catppuccin Mocha flavor, image preview
atuin	SQLite-backed shell history — fuzzy search, directory-scoped, replaces fzf Ctrl+R

Other

Config	Description
bat	cat replacement with syntax highlighting, Catppuccin Mocha theme

Core Tools

These tools are integrated into the ZSH config and expected to be installed:

Essential

Tool	Purpose
neovim	Editor (aliased to vim)
eza	Modern ls replacement
bat	cat with syntax highlighting
fzf	Fuzzy finder (files, dirs, completions)
fd	Fast find replacement
zoxide	Smart cd with frecency
ripgrep	Fast recursive grep
git-delta	Syntax-highlighted git diffs
starship	Cross-shell prompt
atuin	Shell history search

TUI Applications

Tool	Purpose
lazygit	Git TUI client
lazydocker	Docker TUI client
yazi	Terminal file manager

Additional

Tool	Purpose
tmux	Terminal multiplexer
thefuck	Command autocorrection
tldr	Simplified man pages
btop	System monitor
direnv	Per-directory environment variables
dust	Disk usage analyzer
procs	Process viewer
gh	GitHub CLI
just	Task runner

Personal tools

Repo	Purpose
tools	Clone with just tools-clone, on PATH via zsh config

macOS Setup

A Brewfile is included for one-command macOS setup:

brew bundle --file=Brewfile

This installs all CLI tools, fonts, the default terminal emulator, and linters/formatters.

Font

All configs use JetBrainsMono Nerd Font, installed automatically by just install (or just font-install):

• macOS: via Brewfile (font-jetbrains-mono-nerd-font)
• Arch: ttf-jetbrains-mono-nerd (pacman)
• Fedora: jetbrains-mono-fonts-all (dnf) + Nerd Font patch from nerdfonts.com
• Debian: downloaded from nerd-fonts releases

Machine-Specific Config

Use ~/.config/zsh/.zshrc.local for settings specific to one machine (not tracked):

export MY_API_KEY="secret"
alias work='cd ~/projects/work'

Use ~/.config/git/config.local for git credentials (not tracked):

[user]
    name = Your Name
    email = your@email.com