agentic-windows-setup

A reproducible, terminal-first, agentic-engineering environment for Windows — Kun Chen's macOS dotfiles, ported to WSL2. No Nix. It just works.

---

What this is

kunchenguid/dotfiles-mac-nix is Kun Chen's meticulously-built macOS agentic-engineering environment: a keyboard-driven terminal, tmux sessions that survive reboots, Neovim, and a fleet of AI-agent CLIs — all declared with nix-darwin + Home Manager.

agentic-windows-setup brings that same environment to Windows — via rcha0s/agentic-mac-setup — but makes one deliberate, opinionated change: it drops Nix. Instead of porting a macOS-only toolchain and a Linux distro-builder that fights the platform, it puts the entire Unix workspace where it actually belongs on Windows — inside WSL2 Ubuntu — and provisions it with plain apt + nvm. A thin native-Windows layer supplies only the few things WSL genuinely can't: the GUI terminal, fonts, a real browser, and a window manager.

The result is a setup that a Windows developer can stand up with one PowerShell command and get ~1:1 fidelity with Kun's Mac flow — without learning Nix.

Why use it

• One command, reproducible. bootstrap.ps1 is idempotent and reboot-aware. Run it, reboot if asked, run it again. Your machine converges to a known-good state — the same state on every machine.
• No Nix tax. You get the same tools without the Nix language, flakes, or a second package manager to reason about. apt + nvm + npm, the way Linux already works.
• A real terminal workspace. tmux + Neovim + zsh + Starship inside WSL2, rendered by WezTerm on the host. Sessions and layouts persist across reboots (tmux-resurrect + tmux-continuum).
• AI agents, first-class. Kun's agentic CLIs (gh-axi, chrome-devtools-axi, tasks-axi, lavish, no-mistakes, gnhf, treehouse, firstmate) run verbatim inside WSL — including browser automation that drives a real Chrome/Edge on the Windows host over the DevTools Protocol.
• Layered and honest. System concerns live on the host (winget); dev-env concerns live in WSL. Nothing is hidden; every design choice is documented, not improvised.

How it works

Two layers, mapping cleanly onto Kun's own model — the heavy workspace in WSL, a thin shell on the host:

┌────────────────────────── Windows host (thin) ───────────────────────────┐
│  WezTerm  ·  Nerd Font  ·  Chrome/Edge (CDP)  ·  komorebi+whkd  ·  Tailscale │
│                        winget Configuration DSC                            │
└───────────────┬───────────────────────────────────────────────────────────┘
                │  mirrored networking  ·  /mnt/c mount  ·  WSL:Ubuntu domain
┌───────────────┴──────────────── WSL2 Ubuntu (workspace) ──────────────────┐
│  tmux  ·  Neovim  ·  zsh + Starship  ·  nvm + Node LTS                      │
│  agentic stack: gh-axi · chrome-devtools-axi · tasks-axi · lavish ·        │
│                 no-mistakes · gnhf · treehouse · firstmate                  │
└───────────────────────────────────────────────────────────────────────────┘

Three design decisions make it "just work":

1. WSL2 is the workspace (not an afterthought)

tmux is the load-bearing primitive in Kun's setup and has no native Windows port; the whole agentic stack is Unix shell + npm + curl-piped installers. So the Unix tools run in real Linux (WSL2 Ubuntu), and WezTerm on the host renders them with its default domain set to WSL:Ubuntu. You open one window and you're in tmux main.

2. The repo lives on your mounted Windows folder — one source of truth

You clone the repo into your Windows filesystem (the Desktop by convention), where WSL sees it at /mnt/c/Users/<you>/Desktop/agentic-windows-setup. The installer then symlinks the seeded configs (nvim, .tmux.conf, starship.toml, .zshrc.local) from that working tree into your WSL $HOME.

That means there is exactly one copy of every config, editable from either side:

• Edit with Windows tools (VS Code, Explorer) or from inside WSL — both see the same file.
• git pull updates your live dotfiles instantly — no copy or re-sync step.
• Host tools (WezTerm) and WSL tools share the same tree, so the two layers never drift.

3. Mirrored networking bridges WSL to the host browser

Browser automation (chrome-devtools-axi) runs inside WSL but must drive a real GUI browser on the Windows host over the Chrome DevTools Protocol. WSL2's default NAT mode can't reach the host's loopback debug port, so the setup enables mirrored networking (.wslconfig → networkingMode=mirrored) — installed for you by bootstrap.ps1. With it, WSL's localhost:9222 is the host's localhost:9222, and the CDP bridge works with no firewall holes or address juggling. (Details: docs/CDP-BROWSER.md.)

What you get

Terminal · shell · editor · multiplexer — all inside WSL, rendered by WezTerm:

Tool	Role
WezTerm (host)	frameless terminal, default domain WSL:Ubuntu
tmux (WSL)	persistent sessions — tmux-resurrect + tmux-continuum
Neovim (WSL)	oil.nvim, neogit, snacks.nvim, win32yank clipboard bridge
zsh (WSL)	autosuggestions + syntax-highlighting + Starship prompt

Agentic stack — Kun's tools, run verbatim inside WSL:

Tool	Kind	Purpose
gh-axi, chrome-devtools-axi, tasks-axi, lavish, no-mistakes	Claude Code skills	GitHub, browser automation, backlog, HTML-artifact review, push-gate (/no-mistakes)
gnhf	CLI	overnight agent loop
no-mistakes	CLI	local git-proxy that validates code before it reaches the push target
treehouse	CLI	git-worktree pool
firstmate	CLI	multi-agent fleet orchestration

MCP note: these tools are Claude Code skills + CLIs, not MCP servers. The one MCP touchpoint is chrome-devtools-axi, which bridges to the third-party chrome-devtools-mcp server to talk to the host browser.

Host extras — the minimum native layer:

• Hack Nerd Font (tmux status + Starship glyphs)
• Chrome / Edge for the CDP browser bridge
• komorebi + whkd — optional tiling window manager (the amethyst parallel)
• Tailscale — for optional secure remote access to your tmux session

Prerequisites

• Windows 11 (or Windows 10 21H2+) with virtualization enabled in BIOS.
• Administrator access — enabling WSL features and wsl --install require it.
• winget (App Installer) — ships with modern Windows; else install from the Microsoft Store.
• A GitHub account for gh auth login (used by gh-axi / no-mistakes / firstmate).

Quickstart

Clone into your Windows user space (Desktop by convention), then drive everything from bootstrap.ps1:

# From an ELEVATED PowerShell (features + wsl --install need admin):
cd $env:USERPROFILE\Desktop
git clone https://github.com/<you>/agentic-windows-setup.git
cd agentic-windows-setup

# 1. Preview — makes no changes:
powershell -NoProfile -ExecutionPolicy Bypass -File bootstrap.ps1 -DryRun

# 2. Real run:
powershell -NoProfile -ExecutionPolicy Bypass -File bootstrap.ps1

Why -ExecutionPolicy Bypass? A stock Windows box sets the script policy to Restricted, which blocks .ps1 files entirely. Bypass applies to this one invocation; the script then raises your CurrentUser policy to RemoteSigned so the profile it installs (and future runs) work without the flag.

powershell vs pwsh: these commands use powershell.exe (Windows PowerShell 5.1), present on every Windows machine. pwsh (PowerShell 7) is optional — don't assume it's installed.

bootstrap.ps1 will, in order:

1. Enable the WSL2 Windows features (idempotent, reboot-aware — if a reboot is needed it tells you and exits; reboot and re-run).
2. Register the Ubuntu distro (wsl --install -d Ubuntu).
3. Apply host apps via winget configure -f dsc/configuration.dsc.yaml.
4. Install the Hack Nerd Font (not in the winget catalog).
5. Copy host dotfiles (WezTerm, PowerShell profile, komorebi, .wslconfig) into your profile.
6. Run the in-WSL installer — setup/install-wsl.sh (apt + nvm + npm) — which installs the toolbelt, symlinks the dotfiles, and runs setup/agentic.sh.

Flags

Flag	Effect
-DryRun	print planned actions, change nothing
-SkipHost	skip host features / winget / fonts / dotfiles
-SkipWsl	skip distro registration + the in-WSL installer
-SkipAgentic	skip the agentic stack (passed into WSL)
-RemoteAccess	enable the Windows OpenSSH server for remote tmux — see docs/REMOTE-ACCESS.md
-Nix	optional — use a declarative Nix + Home Manager path inside WSL instead of apt/nvm

Inside WSL, setup/install-wsl.sh additionally honors DRY_RUN, SKIP_APT, SKIP_TOOLS, SKIP_ZSHRC, SKIP_AGENTIC, SKIP_SHELL.

The no-Nix apt + nvm path is the default and the one this project is built around. The -Nix path exists for those who specifically want a declarative rebuild, but it is not required — the whole point is that you don't need Nix to get this environment.

After install

Open WezTerm — it drops straight into WSL + tmux main. Then:

1. Press C-a I once to install tmux plugins.
2. Run gh auth login inside WSL.
3. For browser automation, start a host browser with CDP and confirm the bridge — see docs/CDP-BROWSER.md.

Full checklist: docs/HANDOFF.md.

• Remote access to your tmux session (Tailscale + OpenSSH → WSL): docs/REMOTE-ACCESS.md
• Voice dictation (local Whisper/Parakeet, the OpenSuperWhisper replacement): docs/DICTATION.md

Repository layout

bootstrap.ps1              Host entry point (reboot-aware, idempotent, -DryRun)
dsc/configuration.dsc.yaml winget DSC: WezTerm, Git, Chrome, komorebi/whkd, Tailscale
files/                     Seeded configs (wezterm, nvim, tmux, starship, zshrc, .wslconfig)
setup/install-wsl.sh       In-WSL installer (apt + nvm + npm) — the default path
setup/agentic.sh           Installs Kun's agentic skills + CLIs, verbatim
nix/                       Optional declarative path (flake.nix + home.nix) for -Nix
docs/                      Deep-dive docs (see below)

Documentation

Doc	Covers
docs/HANDOFF.md	post-install checklist
docs/PRIMER-WSL.md	WSL2 concepts, mirrored networking, the /mnt/c mount
docs/CDP-BROWSER.md	chrome-devtools-axi ↔ host browser wiring
docs/REMOTE-ACCESS.md	reach your tmux session from anywhere (Tailscale + OpenSSH)
docs/DICTATION.md	local voice dictation
docs/PRIMER-TMUX.md, docs/PRIMER-ZSH.md, docs/LEARN-*.md	ported primers from upstream

FAQ

Why WSL2 instead of native Windows tools? tmux has no native Windows port, and the agentic stack is Unix shell + npm. WSL2 is real Linux, so the Mac tools run unchanged.

Why drop Nix? Nix on Windows means a macOS-oriented toolchain plus a second package manager fighting the platform. apt + nvm inside WSL gets you the same tools with far less friction — and the whole promise here is "it just works." The declarative Nix path is still available via -Nix if you want it.

Why does the repo live on the Desktop / /mnt/c? So there's one working tree that both Windows and WSL edit, with dotfiles symlinked in. git pull updates your live config with no sync step, and host + WSL layers never drift.

Why mirrored networking? It makes WSL and the host share localhost, which the CDP browser bridge needs. bootstrap.ps1 installs the .wslconfig for you (without clobbering an existing one); apply it with wsl --shutdown.

Credits

Ported from rcha0s/agentic-mac-setup, which derives from Kun Chen's kunchenguid/dotfiles-mac-nix and his agentic tooling (gh-axi, chrome-devtools-axi, tasks-axi, lavish, gnhf, no-mistakes, treehouse, firstmate). Shared dotfiles are kept byte-for-byte identical to upstream so improvements flow both ways.