Same setup. Same agent behavior. Every machine.

A concrete, opinionated playbook for setting up a dev environment that works on Mac, Linux, Windows+WSL, and cloud VMs — and is productive for agentic AI engineering specifically. Not "favorite tools"; the discipline of parity.

— start here

Pick your platform first.

"You're not choosing forever. But pick one as primary — the parity discipline assumes you have a primary that you treat as the source of truth."

Read chapter 01 to decide your primary OS. Then either run through the fresh-machine setup checklist for the bulk of the install, or read the playbook chapters in order. The dotfiles pattern in chapter 08 is the highest-leverage move once the basics are working.

— I

Playbook — nine focused chapters

Each chapter is opinionated, concrete, and full of copy-pasteable commands. Read in order for adoption; skim by topic for reference.

Pick Your Platform

Mac · Linux · Windows+WSL2

The three viable choices, when each is right, what NOT to do (dual-boot, custom distros, three OSes). Recommendations in order.

Decision

Shell, Prompt, Multiplexer

bash/zsh · Starship · tmux/zellij

The three load-bearing layers. Modular shell config, Starship setup, multiplexer with one-keystroke pane layouts. Common pitfalls.

Foundation

Modern Unix Tools

rg · fd · bat · eza · fzf · zoxide · atuin

The rust-rewritten classics. Why they matter for agent-friendly output. Per-platform install. fzf-based widget patterns. Anti-patterns.

Tooling

Runtime Version Management

mise · uv · rustup

One tool for Python, Node, Go, Ruby, Java versions. Plus uv for Python packages and rustup for Rust. Per-project .mise.toml pinning. Common pitfalls.

Tooling

Cross-Platform Parity

The discipline that prevents drift

Where parity breaks: line endings, paths, fonts, shells, default tools, notifications, cloud CLIs. Each with the failure mode and the fix. The pragmatic test for "is my parity good?"

Load-bearing

WSL-Specific

Windows + Linux on one machine

WSL2 setup, the two-filesystem rule, tooling that bridges Windows ↔ WSL, GPU passthrough for local LLMs, common pitfalls.

Platform

AI Tooling Layer

Claude Code · Cursor · MCP servers · local models

The four layers (project context → harness → MCP → local runtime). What to install, how to wire it together. Anti-patterns.

AI layer

Dotfiles Pattern

Idempotent installer · git-tracked configs

Repo structure, idempotent installer, local overrides, public vs private dotfiles, adoption rhythm. The single most important parity tool.

High leverage

Troubleshooting

Common failure modes · diagnostic commands

Slow shell startup, command not found, mise versions not activating, line ending issues, SSH failures, ANTHROPIC_API_KEY 401, WSL slowness, font glyphs missing — each with diagnosis + fix.

Reference

— II

Checklists — operational sequences

Step-by-step lists for the recurring operational moments.

II.1

Fresh Machine Setup

Brand-new laptop or VM

8-phase sequence: foundation → dotfiles clone → modern Unix tooling → runtime mgmt → AI tooling → project setup → verify → hardening. ~2 hours total.

Operational

II.2

Parity Audit

Bi-annual drift detection

Setup parity, config parity, behavior parity, cross-platform behavior, agent-specific parity, documentation parity. Each with acceptance criteria.

Operational

II.3

Agent Readiness

Pre-session check

Project-level setup, MCP/tool access, repository hygiene, verification, boundaries, observability, resume/continuity. Anti-readiness signs that mean stop.

Operational

— III

Reference Configs — copy-pasteable starting points

Working configs for the load-bearing layers. Tweak to taste; the structure is what matters.

III.1

starship.toml

Cross-platform prompt config

Working Starship config: directory + git + runtime versions + cloud context. Tuned to show what matters and skip what doesn't.

Config

III.2

tmux.conf

Multiplexer config with quad-pane macro

Working tmux config: Ctrl-a prefix, mouse mode on, vi-style copy mode, one-keystroke pane layouts (Q for 2x2 quad).

Config

III.3

mise.toml

Reference per-project runtime config

Pinned tools, per-project env vars, optional task definitions. Drop at project root; mise activates on cd.

Config

III.4

install.sh

Idempotent dotfiles installer skeleton

Detects platform (macOS / Linux / WSL / Windows), installs packages, symlinks configs, runs runtime managers, runs platform-specific post-install. Safe to re-run.

Foundation

— for non-github readers

Send a quick note.

Used the playbook to set up your own environment? Hit a gap or a platform-specific failure? Have a war story? This form goes straight to the maintainer.

If you have a GitHub account, opening an issue is preferred. This form is the path for everyone else.