Skip to content

Philosophy & Tech Stack

This repository is built on a specific set of tools chosen for their speed, reliability, and developer experience. Here is the reasoning behind those choices.

Core Principles

  1. Idempotency: You should be able to run the install script 100 times in a row without breaking anything.
  2. Speed: Latency kills flow. Tools must start instantly.
  3. Portability: The same config should work on a high-end Arch workstation, a MacBook Pro, and a headless Debian server.
  4. Declarative Configuration: Define what you want, not how to get it.

The Stack

1. Tool Management: Mise

Why not asdf, nvm, pyenv, or brew?

  • Speed: Mise is written in Rust and is orders of magnitude faster than asdf.
  • Unified: It replaces nvm (Node), pyenv (Python), rustup (Rust), and even brew (for CLI tools) in one binary.
  • Env Vars: It handles environment variables better than direnv, loading them only when tools are active.
  • No Shims: Usage of mise activate modifies PATH directly, avoiding the overhead of shims for every command execution.

2. Dotfile Manager: Chezmoi

Why not GNU Stow or a Bare Git Repo?

  • Templates: We need different configs for Linux vs macOS vs WSL. Chezmoi's Go templates {{ if .chezmoi.os == "linux" }} make this trivial.
  • Secrets: Built-in support for age encryption allows us to commit encrypted secrets safe inside the repo.
  • Drift Detection: chezmoi diff shows exactly what has changed on your local machine compared to the repo.

3. Server Provisioning: Ansible

Why not shell scripts?

  • Idempotency: Ansible modules (apt, user, copy) handle state checking automatically.
  • Scale: Deploying to 1 server or 100 uses the same playbook.
  • Maintainability: YAML is easier to read and maintain than complex bash conditionals.

4. Shell: Zsh + Antidote

Why not Bash or Fish?

  • Vs Bash: Zsh offers better interactive features (completion, globbing) while maintaining decent POSIX compatibility.
  • Vs Fish: Fish breaks POSIX compliance, making it hard to paste generic commands from the web. Zsh is the sweet spot.
  • Antidote: A lightning-fast package manager for Zsh plugins. It statically generates a .zsh_plugins.zsh file, avoiding the startup cost of dynamic loading.

5. Editor: Neovim

Why not VS Code?

  • Speed: Starts in milliseconds.
  • Flow: Never leaving the keyboard keeps you in the "zone".
  • Remote: Works perfectly over SSH/Mosh on headless servers.
  • (We do install VS Code for when a GUI debugger is strictly necessary).

6. Terminal: WezTerm / Alacritty

  • GPU Accelerated: Rendering text at 60fps+.
  • Lua Config (WezTerm): Programmable configuration that matches the flexibility of the rest of the stack.