Install & set up

Run make to apply configuration. Run make install to install selected tools and configure them. Both use this machine’s configuration sets.

Set up a new machine

Requires Git, Make, and Bash on macOS or Linux. The one-line quick start clones or reuses ~/.files and runs the minimal bootstrap. To run each step yourself:

1. Clone and initialize the native configuration.

git clone https://github.com/lanej/dotfiles.git ~/.files
cd ~/.files
make base

2. Choose this machine’s tools. Edit ~/.config/dotfiles/config.toml; use workstation for the broad setup, then add work-context sets or individual overrides as needed:

sets = ["workstation"]

The file respects XDG_CONFIG_HOME and DOTFILES_CONFIG. make base creates it only when missing and selects the native macos or linux baseline. See configuration composition for available sets and override examples. To add Mermaid CLI and its headless browser for Neovim diagrams, set tools.mermaid = true.

3. Bootstrap, preview, and install.

make bootstrap
make plan
make install

Open a new shell after setup to load the linked shell configuration.

Choose a setup command

Command	Use it to
make	Reapply the native baseline, selected bundles, and individual overrides. Configuration only; requires Python 3.11+.
make base	Initialize missing machine TOML and link the built-in native baseline, without Python.
make shell git	Link basic shell and Git configuration without Python.
make bootstrap	Apply the native baseline and install only uv and Python. Ignores machine TOML.
make plan	Preview the selected tools and configuration before installation.
make install	Install selected tools and apply their configuration and integrations. Ensures uv and Python are available first.

make configure, make setup, and make all are aliases for make. bash bootstrap.sh and bash bootstrap.sh install are the script equivalents of the two installation stages. Neither stage pulls updates or switches branches. Linting and tests run separately with make lint and the test targets.

make lua-check runs StyLua and Luacheck on every tracked or untracked, non-ignored Lua source file, including Neovim, WezTerm, tests, scripts, fixtures, and generated modules. make lua-format applies formatting before analysis. The editor tool set installs both tools through Homebrew, APT, or Pacman; other systems need Luacheck installed with LuaRocks first. Generated data tables retain their generator’s layout with StyLua directives; parsing and static analysis still cover those files. The Lua quality workflow runs the same check for Lua changes in pull requests and on master.

Update an existing machine

From the checkout, pull the latest changes and reapply configuration:

cd ~/.files
git pull --ff-only
make

Open a new shell to load shell changes. Run make plan followed by make install if you also want to install newly selected tools.

Shell completions

recomp is the completion refresh helper. Run it in the current Zsh session after installing a supported CLI or adding a completion file:

recomp

It regenerates completions for supported tools on PATH, clears stale completion definitions, and reloads completion in the current shell. No shell restart or plugin setup is needed.

Command	Effect
recomp	Generate completions and reload the current Zsh session.
recomp add <tool>	Find a generator, register it locally, and load its completion now.
make zsh-completions	Generate completion files only; open a new shell afterward.
make / make configure	Generate completions as part of configuration when the shell set is selected.

make install and make zsh-config also generate completions. Supported tools include fd, uv, Rust, GitHub CLI, Codex, Zellij, and Atuin; the generator script lists every built-in command. Missing tools are skipped. Tools without generators continue using packaged completions or existing shell integrations.

Register a local tool

Use recomp add for a work-only or other locally installed CLI:

recomp add epf

For a new tool, it tries epf completions zsh, then epf completion zsh. It validates the output before saving the working command and loads the completion in the current shell. Existing local registrations and built-in generators are reused first. Both the target and generator must already be installed.

For a different command or an override, supply the generator explicitly:

recomp add cargo \
  rustup completions zsh cargo

Registrations stay outside the checkout in ~/.config/dotfiles/completions (or $XDG_CONFIG_HOME/dotfiles/completions). Future make and recomp runs reuse the saved command. Repeating the same registration leaves the file unchanged; an explicit replacement updates that tool’s entry without duplicating it. Built-in generators need no extra local entry unless you override them.

Failed validation leaves the registry and last working completion intact. Hand-written completion files and symlinks are preserved. If the registry itself is a symlink, edit it directly so its managed destination stays intact.

Edit the local registry manually

Each non-comment line contains a completion name, a generator command, and its arguments, separated by spaces or tabs. For example:

epf epf completions zsh

Local entries override built-ins, and the first entry for a name wins. Run recomp after editing. Arguments are literal words: shell quoting, expansions, and pipelines are not evaluated. recomp add rejects arguments containing whitespace; put complex commands in an executable wrapper on PATH and register that command instead. Missing targets are skipped during normal refresh; registration does not install software.

Completion files, preservation, and older fd versions

Generated files live at ~/.zsh/completions/_<tool>. Failed or empty generators report failure and keep the last working file. Hand-written files and symlinks are preserved; move one aside and rerun setup to let dotfiles manage it. Unchanged output preserves the file and cache; changed output invalidates the dump for the next shell. recomp also picks up completion files added by hand and ignores insecure completion directories.

Older fd builds without --gen-completions use their packaged _fd from standard Zsh completion locations or the fd release directory. If neither source is available, setup explains how to install it and preserves the previous file. make test-zsh-completions exercises generation and active-shell refresh.

Recover an incomplete setup

The configuration checklist shows green ✓ for completed steps and red ✗ with diagnostics for incomplete steps. Independent steps continue after a failure; the command exits nonzero after the full checklist if anything needs attention. Install missing dependencies or fix the reported issue, then rerun the same target. Existing links and user configuration are safe to reuse.

Zsh starts silently during a partial install, keeping the basic prompt, completion, and history available. The custom fzf integration activates in a new shell when both fzf and fd are installed. Failed integration generators keep working cached hooks. Existing fzf-tab and tmux plugin directories are preserved, including local tmux plugins without Git metadata; failed TPM installation reports an error for manual recovery.

The native platform set is selected automatically; explicitly requesting unsupported platform tools fails before writing configuration.

Set	Native configuration
linux	X11, Polybar, bspwm/sxhkd/rofi
macos	Yabai/skhd

Color is enabled in terminals. Use NO_COLOR=1 to disable it or CLICOLOR_FORCE=1 to enable it in captured output. The setup requirements record the intended boundaries and acceptance criteria.

Check shell startup and measure performance

make test-zsh-startup checks partial-install startup. make benchmark-zsh-startup measures the current home’s interactive login-shell startup and exit over 30 runs after three warmups. It reports median and p95 wall time for zsh -d -i -l -c exit, including process launch and logout, with global rc files skipped. It inherits your HOME and PATH; run it on your workstation for representative timings. Use ZSH_BENCHMARK_ARGS='--runs 60 --json' for more samples and JSON output.

AI tool integrations

Command	Integration
make claude-shared	Link shared ai/skills and ai/agents into Claude’s installed directories, preserving local entries. Included in make claude.
make codex	Expose shared ai/skills through ~/.agents/skills/dotfiles, preserving local Codex skills.
make codex-skills	Refresh normalized file-linked or lowercase skill entrypoints in ~/.codex/dotfiles-skills. Missing external sources are reported and skipped.

make configure with the AI bundle (or make claude) also removes user-scope Claude Code plugins listed in claude/blocked-plugins.json when the Claude CLI is available. Add a marketplace-qualified ID there to retire a plugin; Superpowers is the initial entry. Already-absent plugins are a no-op. Invalid configuration, inspection, or uninstall failures mark that step incomplete.

Worktree tracking and resource limits

Treehouse manages reusable agent worktree slots. The optional worktree policy tracks linked worktrees across registered repositories, including worktrees created outside Treehouse, and supports independent per-repository and global count and disk budgets. Limits are disabled by default.

The optional worktrees bundle installs the standalone worktree command for fresh task checkouts, explicit finish protection, global tracking, budgets, and safe pruning. Existing Treehouse pools and agent defaults remain available while the replacement is evaluated.

The base set installs the patched Git runtime from a pinned platform package. Shared Git configuration enables global tracking and admission hooks without per-repository installation; budgets remain disabled until configured. Stock Git keeps inventory refreshed through post-checkout; callers need explicit preflight checks to block creation. Treehouse manages leases independently of this machine-wide inventory.