dotfiles

My ~/.config. One repo for every machine: macOS, Linux desktops, headless Linux servers and (optionally) Windows.

Neovim is the centrepiece, tuned for reading unfamiliar code and with Claude wired in. Around it are zsh, tmux, Ghostty and one colour palette shared by every tool.

Full docs: run make serve and open http://127.0.0.1:8000, or browse docs/ here on GitHub. This README is the short version.

The stack

Layer	Choice	Notes
Editor	Neovim ≥ 0.12	lazy.nvim, native LSP, fzf-lua, blink.cmp, conform, Claude Code + CodeCompanion + Copilot
Shell	zsh, no framework	starship prompt, fzf, fzf-tab, zoxide, eza, autosuggestions
Multiplexer	tmux	prefix Ctrl-a, auto-attaches over SSH
Terminal	Ghostty (Alacritty fallback)	JetBrainsMono Nerd Font, blur/glass
Git	git + delta + lazygit + gh / gh-dash	PR review inside Neovim (diffview, octo)
Containers	docker / kubectl aliases, lazydocker, k9s	configs pulled back into ~/.config
Theme	tokyonight · solarized-osaka · catppuccin-mocha	theme <name> switches every tool at once

Tools

Everything make tools installs, and what each one is for. The install list itself lives in bootstrap (BREW_FORMULAE, BREW_CASKS). make docs fails if a tool there is missing from this table.

Group	Tool	What it does here
Editor	neovim	the editor; config in nvim/
	tree-sitter-cli	builds the syntax parsers nvim-treesitter uses
	ripgrep · fd	grep and file finding, used by the Neovim pickers and the shell
	node	runtime for Mason's language servers (vtsls, basedpyright, prettier) and Copilot
	shellcheck	shell linting, in Neovim and on scripts/
Shell	starship	prompt, coloured from the active theme
	fzf	fuzzy finder: Ctrl-r history, Ctrl-t files, fzf-tab completion
	zoxide	z <dir> jumps to frequent directories
	eza · bat	ls and cat replacements with icons, git status and syntax highlighting
	zsh-autosuggestions · zsh-syntax-highlighting	fish-style suggestions and command colouring
	tlrc	tldr <cmd>: short, example-first man pages
Terminal	ghostty	the daily terminal (macOS cask)
	alacritty	fallback terminal
	font-jetbrains-mono-nerd-font	the font everywhere; Nerd Font glyphs for icons
	tmux	multiplexer, prefix Ctrl-a, auto-attaches over SSH
Git	delta	side-by-side, syntax-highlighted diffs for git diff/log
	lazygit	git TUI, also Space g g in Neovim
	gh	GitHub CLI; also runs the gh-dash PR dashboard extension
Containers	lazydocker	Docker TUI
	k9s	Kubernetes TUI
Runtimes	mise	per-project node / python / go versions from mise.toml
System	btop	process and resource monitor
	mtr	traceroute and ping combined
	ncdu	find what's eating disk space
	watch	re-run a command every few seconds
	jq	JSON on the command line

Not from Homebrew, so make verify prints their versions for comparing machines: Claude Code (claude, native installer) and mkdocs-material (docs site). Inside Neovim, Mason installs the language servers and formatters. Run :Mason to see them.

Quick start

This repo is ~/.config, so clone it there. make install links the few files that live outside ~/.config and reports missing tools without installing them.

# macOS and Linux: Homebrew is the package manager on both
# (Linux needs build tools + zsh first, see docs/setup.md)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

git clone https://github.com/codephilip/dotfiles.git ~/.config
cd ~/.config
make tools | sh    # install the tool list from bootstrap
make verify        # dry run: what would be linked, what's missing
make install       # link ~/.zshrc ~/.tmux.conf ~/.gitconfig (~/.ssh/config), generate theme files
exec zsh
nvim               # plugins install themselves; :Mason for language servers

Windows: make windows from Git Bash with scoop. See docs/windows.md.

After that, do the one-time logins a public repo can't hold: restore ssh/config, gh auth login, gh extension install dlvhdr/gh-dash, install Claude Code, :Copilot auth in Neovim, and put secrets in ~/.zshrc.local. On a Mac, also fix key repeat. docs/setup.md has all of it: how the repo is laid out on disk, the per-distro Linux steps, the first-run list, a checklist to confirm it worked, adopting an existing ~/.config, and keeping machines in sync.

Everyday commands

make help            # every make target
make verify          # health report for this machine; changes nothing
make install         # re-run after a git pull (idempotent)

theme list           # themes, active one marked
theme next           # cycle; theme <name> to pick one

git-commands         # terminal cheatsheets rendered with bat. Also:
                     #   tmux- zsh- nvim- vim- docker- k8s-commands

Inside Neovim: press Space and wait, and which-key lists everything. :Doctor checks the setup's health.

Layout

~/.config/
├── bootstrap             symlinks + tool report  (make install / verify / tools)
├── Makefile              entry point for everything
├── nvim/                 Neovim: init.lua, lua/config, lua/plugins, lazy-lock.json
├── zsh/                  .zshrc (→ ~/.zshrc), prompt fallback, vendored fzf-tab
├── tmux/tmux.conf        → ~/.tmux.conf
├── git/                  gitconfig (→ ~/.gitconfig), global ignore, aliases
├── ghostty/  alacritty/  terminals
├── starship.toml         prompt (generated from the palette by scripts/gen-starship.py)
├── theme/                palettes (source of truth) + the active theme name
├── docker/  k8s/         aliases, lazydocker and k9s configs
├── gh/  gh-dash/         GitHub CLI and PR dashboard
├── scripts/              theme, newscript, windows-setup, gen-starship.py
├── command-cheatsheets/  terminal-readable references
├── docs/  mkdocs.yml     the docs site
└── brief/                one-page executive brief (→ docs/assets/*.pdf)

Some files are generated and gitignored: ghostty/theme.conf, alacritty/theme-current.toml, git/theme.gitconfig, starship-current.toml and the k9s skin. make install creates them. Don't edit them by hand.

Not tracked, on purpose: ssh/, ~/.zshrc.local, ghostty/local.conf, and the state other tools write into ~/.config (gh tokens, stripe keys, caches). .gitignore is an allowlist: everything at the top level is ignored except the directories it names, so a new tool's directory is invisible to git until you add it.

Docs

The long-form docs are a MkDocs Material site in docs/:

brew install mkdocs-material   # once (or: pip install mkdocs-material)
make serve                     # live reload at http://127.0.0.1:8000
make docs                      # strict build into ./site; fails on dead links

Page	What's there
Setup	how it works, new machine on macOS / Linux / Windows, first-run logins, syncing machines
Neovim	architecture, every plugin, key bindings, PR review, CI, AI workflow
Shell	zsh, prompt, fzf bindings, aliases and functions
tmux	every key, stock and ours
Docker and Kubernetes	aliases, lazydocker, k9s
Terminal	Ghostty, Alacritty, fonts
Theming	how one palette reaches every tool, adding a theme
Git	config, aliases, delta
Windows	scoop + MSYS2 setup
Troubleshooting	failures that actually happened, and their fixes
Maintenance	rules, checklists and the monthly routine that keep this repo accurate

Keeping it maintained

The short version of docs/maintenance.md:

• One source of truth per fact. The tool list is in bootstrap, colours are in theme/palettes/, plugin versions are in nvim/lazy-lock.json. Docs link to these and don't copy them.
• Machine-specific settings go in local files (~/.zshrc.local, ghostty/local.conf), not in hostname checks.
• .gitignore is an allowlist. Nothing at the top of ~/.config is tracked unless .gitignore names it with !/<dir>/, so a new tool's state never shows up by accident. Track a new config on purpose.
• Private lines get # local-only. In gh-dash/config.yml, a line ending in # local-only stays on this machine and is never committed.
• Monthly: brew upgrade, run the Neovim routine, make verify, make docs. Commit, then on each other machine run git pull && make install && nvim "+Lazy restore".