Universal Dotfiles

Production-grade portable one-click dotfiles for Linux and Windows 11 software engineering environment.

Auto-detecting, auto-bootstrapping, idempotent, gracefully degrading, full terminal tooling, fully vibecoding-enabled.

---

Core Features

Editor & Terminal

• Neovim 0.13+ (beta) with vim.pack manager + lockfile, LSP/Treesitter config, native completion, and the builtin dir browser
• WezTerm GPU-accelerated terminal (IosevkaTerm Nerd Font)
• Rose Pine theme across all configs

Development Tools

• 21 LSP servers for complete language intelligence (jdtls excluded on Windows)
• 28 Treesitter parsers for advanced syntax highlighting
• 40+ CLI tools for modern development workflows (fzf, yazi, zoxide, bat, eza, lazygit, gh, ripgrep, fd, sqlite, tokei, btop, repomix, docker-compose, helm, kubectl)

AI-Native Agentic Development

• Full support for Claude Code and OpenCode
• 3 MCP servers: context7, playwright, repomix
• Auto-detect & trigger format/lint/check: Git pre-commit/commit-msg hooks
• Statusline hook for Claude Code (unified bash script, auto-registered in settings.json)
• System instruction sync across all repos (AGENTS.md, GEMINI.md, RULES.md redirect to .claude/CLAUDE.md)

Automation & Safety

• Idempotent bootstrap and update-all (safe to run multiple times)
• Auto-detection with graceful degradation
• OneDrive-aware on Windows
• Timestamped backup/restore before major changes

Tested Platforms

• Linux (Ubuntu 26.04+)
• Windows 11 (PowerShell 7+)

---

Quick Start

Required Clone Location: This repository MUST be cloned to ~/dev/github/dotfiles.

For Docker/Kubernetes setup, see DOCKER_K8S.md.

Linux

git clone https://github.com/lavantien/dotfiles.git ~/dev/github/dotfiles
cd ~/dev/github/dotfiles
chmod +x allow.sh && ./allow.sh
./bootstrap.sh
chsh -s $(which zsh)
exec zsh

macOS

git clone https://github.com/lavantien/dotfiles.git ~/dev/github/dotfiles
cd ~/dev/github/dotfiles
chmod +x allow.sh && ./allow.sh
./bootstrap.sh
exec zsh

Windows (PowerShell 7+)

git clone https://github.com/lavantien/dotfiles.git $HOME/dev/github/dotfiles
cd $HOME/dev/github/dotfiles
.\bootstrap.ps1
. $PROFILE

Verify Installation

which n  # Should point to nvim
which lg  # Should point to lazygit
up  # Runs update-all

---

Available Commands

Script	Purpose
bootstrap	Initial setup - installs package managers, SDKs, LSPs, tools, deploys configs
deploy	Deploy configs and scripts (Neovim, git hooks, shell, Claude Code settings, OpenCode MCPs, ~/dev scripts), see deploy options below
update-all (up)	Update all package managers and system packages (20+ managers)
git-update-repos	Clone/update ALL GitHub repos via gh CLI, optionally sync system instructions
sync-system-instructions	Sync AI system instructions (AGENTS.md, GEMINI.md, RULES.md) to all repos, remove stale CLAUDE.md
healthcheck	Check system health - verify tools, configs, git hooks
backup	Create timestamped backup before major changes
restore	Restore from a previous backup
uninstall	Remove deployed configs (keeps installed packages)

Windows uses .ps1 scripts, Linux/macOS uses .sh scripts.

Bootstrap Options

Option	Bash	PowerShell	Default
Non-interactive	-y, --yes	-Y	Prompt for confirmation
Dry-run	--dry-run	-DryRun	Install everything
Categories	--categories sdk	-Categories sdk	full
Verbose	--verbose	-VerboseMode	Show detailed output

Update-All Options

Option	Bash	PowerShell	Purpose
Skip pip updates	--skip-pip	-SkipPip	Skip pip package updates (speeds up update)

Usage with alias: up --skip-pip (bash) or up -SkipPip (PowerShell)

Deploy options

Option	Bash	PowerShell	Purpose
Skip config deployment	--skip-config	-SkipConfig	Deploy ~/dev scripts only, skip all config deployment
Verbose file logging	--verbose	(always on)	Log each copied file
Pre-deploy backup	--backup	-Backup	Force backup before deploy (also via backup_before_deploy config)
Help	--help	(Get-Help)	Show usage

Both deploys write a ~/.dotfiles-installed marker (timestamp, version, OS) read by uninstall. -DotfilesDir and POWERSHELL_PROFILE_CONFIG are Windows-only parameters; bash derives the repo location from the script path and honors XDG_CONFIG_HOME.

Installation Categories

Category	Description
minimal	Package managers + git + CLI tools only
sdk	Minimal + programming language SDKs
full	SDK + all LSPs + linters/formatters (default)

Configuration (Optional)

All scripts use hardcoded defaults by default (categories: full, interactive prompts).

cp .dotfiles.config.yaml.example ~/.dotfiles.config.yaml
vim ~/.dotfiles.config.yaml
./bootstrap.sh  # Auto-detects config

Configuration Priority: Command-line flags > Config file > Hardcoded defaults

Setting	Values	Default
categories	minimal, sdk, full	full
editor	nvim, vim, code, nano	(none)
theme	rose-pine, rose-pine-dawn, rose-pine-moon	(none)
github_username	your github username	lavantien
base_dir	path to git repos	~/dev/github
auto_commit_changes	true, false	false
auto_update_repos	true, false	false
backup_before_deploy	true, false	false

Health & Troubleshooting

./healthcheck.sh

# JSON output (for CI/CD)
./healthcheck.sh --format json

Issue	Solution
Git hooks not running	git config --global core.hooksPath ~/.config/git/hooks
PowerShell execution policy	Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Neovim plugins not installing	In Neovim run :packupdate or press <leader>u
zoxide not jumping	Use directories normally for a few days to let zoxide learn

---

Complete Tools/Packages Matrix

Language	LSP	Tester	Formatter	Linter	Type Check
Bash	bashls	bats	shfmt	shellcheck	-
PowerShell	powershell_es	Pester	Invoke-Formatter	PSScriptAnalyzer	PSScriptAnalyzer
Go	gopls	go test	gofmt, goimports	golangci-lint	go vet
Rust	rust-analyzer	cargo test	rustfmt	clippy	cargo check
Python	pyright	pytest	ruff, black	ruff	mypy
JavaScript/TypeScript	ts_ls	jest	prettier	eslint	tsc
HTML	html	-	prettier	-	-
CSS/SCSS/SASS	cssls	-	prettier	stylelint	-
Svelte	svelte	-	prettier	-	svelte-check
C/C++	clangd	Catch2	clang-format	clang-tidy, cppcheck	compiler
C#	csharp_ls	dotnet test	dotnet format	Roslyn analyzers	dotnet build
Java	jdtls (Linux/macOS only)	JUnit	checkstyle	checkstyle	javac
PHP	intelephense	php, PHPUnit	pint	PHPStan, Psalm	-
Scala	metals	ScalaTest	scalafmt	scalafix	scalac
Lua	lua_ls	busted	stylua	selene	-
Typst	tinymist	built-in	tinymist	tinymist	-
Dockerfile	docker_ls	-	-	hadolint	-
Docker Compose	docker_ls	-	prettier	-	-
Helm	helm_ls	-	prettier	-	-
Kubernetes YAML	yamlls	kubectl	prettier	yamllint	-
YAML	yamlls	-	prettier	yamllint	-
TOML	tombi	-	taplo	-	-

CLI Tools

fzf, yazi, zoxide, bat, eza, lazygit, gh, ripgrep, fd, sqlite, tokei, btop, repomix, docker-compose, helm, kubectl

MCP Servers (Claude Code & OpenCode)

context7, playwright, repomix

Diagram Generation

mermaid-cli (mmdc) - Generate Mermaid diagrams from command line

AI Applications (Windows)

ComfyUI Desktop - AI image generation (requires comfy install after bootstrap)

---

Hooks & Config Merging

Git Hooks

Pre-commit: auto-format, lint, type-check, re-stage fixed files

Commit-msg: enforce Conventional Commits (feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert)

Platform-specific: .sh for Linux/macOS, .ps1 for Windows

Claude Code Hooks

Statusline uses a unified bash script (statusline.sh) on both Linux and Windows (via Git Bash), registered in ~/.claude/settings.json by the settings injection below.

Quality checks can be configured per-project using project-specific hooks or MCP servers.

Claude Code settings injection

Deploy merges the committed .claude/settings.template.json into ~/.claude/settings.json on every run, on both platforms:

• Missing fields are added recursively at every level
• Existing values are never overwritten, local tweaks win
• env.ANTHROPIC_AUTH_TOKEN is deliberately absent from the template and always preserved
• When settings.json does not exist it is created from the template
• Linux/macOS uses jq with a python3 fallback, Windows uses native PowerShell JSON
• Fill-missing never removes keys, so prune the template manually when a setting is retired

Injected top-level fields:

Field	Template value	Purpose
env	13 variables (table below)	API endpoint, models, limits, feature flags
model	glm-5.3[1m]	Default model
statusLine	bash ~/.claude/statusline.sh	Statusline command
enabledPlugins	31 plugins, all enabled	Plugin enablement
alwaysThinkingEnabled	true	Extended thinking by default
autoUpdatesChannel	latest	Update channel
tui	fullscreen	Terminal UI mode
skipDangerousModePermissionPrompt	true	Skip dangerous-mode prompt
teammateMode	auto	Agent teams mode

Injected env variables:

Variable	Value	Purpose
ANTHROPIC_BASE_URL	https://api.z.ai/api/anthropic	API endpoint
API_TIMEOUT_MS	3000000	Request timeout
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC	1	Disable telemetry traffic
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS	1	Enable agent teams
CLAUDE_CODE_ENABLE_AUTO_MODE	1	Enable auto mode
CLAUDE_CODE_MAX_OUTPUT_TOKEN	131072	Max output tokens
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE	93.75	Autocompact trigger percentage
CLAUDE_CODE_AUTO_COMPACT_WINDOW	1000000	Autocompact context window
ANTHROPIC_DEFAULT_HAIKU_MODEL	glm-5.3-flash[1m]	Haiku-class model override
ANTHROPIC_DEFAULT_SONNET_MODEL	glm-5.3[1m]	Sonnet-class model override
ANTHROPIC_DEFAULT_OPUS_MODEL	glm-5.3[1m]	Opus-class model override
CLAUDE_CODE_EFFORT_LEVEL	max	Reasoning effort
CLAUDE_CODE_SUBAGENT_MODEL	glm-5.3[1m]	Sub-agent model override

enabledPlugins entries: glm-plan-usage@zai-coding-plugins, repomix-commands@repomix, repomix-explorer@repomix, repomix-mcp@repomix, and @claude-plugins-official for frontend-design, context7, feature-dev, code-review, commit-commands, typescript-lsp, playwright, agent-sdk-dev, pr-review-toolkit, pyright-lsp, gopls-lsp, rust-analyzer-lsp, csharp-lsp, php-lsp, jdtls-lsp, clangd-lsp, lua-lsp, code-simplifier, superpowers, claude-code-setup, chrome-devtools-mcp, plugin-dev, remember, microsoft-docs, postman, claude-security, math-olympiad.

OpenCode Config Merging

~/.config/opencode/opencode.json is deep-merged (not overwritten) on both platforms:

• Adds missing MCP servers from the platform template
• Updates template-managed values that changed (stale URLs, commands)
• Repairs a malformed scalar mcp section
• Preserves user-added servers and user-added keys

Claude Code Windows LSP Patching

npm-installed LSPs (typescript-language-server, pyright-langserver, intelephense) need cmd.exe /c wrapper. Auto-patches marketplace.json to fix spawn EINVAL errors. On Linux/macOS, deploy strips the same cmd.exe wrappers if a marketplace.json was carried over from a Windows machine.

MCP Server Manual Patching (Windows)

On Windows, MCP servers that use npx (like zai-mcp-server) also need the cmd.exe /c wrapper in ~/.claude.json:

"mcpServers": {
  "zai-mcp-server": {
    "command": "cmd.exe",
    "args": ["/c", "npx", "-y", "@z_ai/mcp-server"]
  }
}

This fixes the "Windows requires 'cmd /c' wrapper to execute npx" warning in MCP diagnostics.

GUI Applications Post-Installation

ComfyUI Desktop (Windows): After bootstrap via winget, run comfy install to complete setup:

comfy install

This installs required models and dependencies for AI image generation.

---

Neovim

Leader key is Space.

Unmapped native keys stay live: Q toggles a multicursor ([count]Q places one per search match, q= follow mode, gQ restore, CTRL-L clears), gc and gcc comment, v_an and v_in grow or shrink the treesitter selection, v_]N and v_[N jump to sibling nodes, v_al and v_il select the buffer or line, and the LSP defaults K, grn, gra, grr, gri, gO, grt, grx, [d, ]d, and <C-W>d work without any plugin.

Day-to-day usage guide

Big picture

The config is builtin-first. Neovim 0.13 itself does editing, completion, LSP, diagnostics, folding, commenting, multicursor, and file browsing. The 7 plugins only fill gaps: fzf-lua for pickers, treesitter for parser installs, lspconfig for server definitions, rose-pine for color, the two preview plugins for documents, devicons for icons.

Two options change the daily rhythm more than any keybinding. Autosave is always on (autowriteall plus a TextChanged autocmd), files write themselves while you type, so you almost never run :w and :q is safe. Autoread with the 0.13 fs watcher reloads files changed underneath you by formatters, code generators, or another pane. Between the two, buffer state and disk state stay glued together with zero keystrokes.

Getting around

<leader>f finds files, <leader>z live-greps the project as you type, <leader>/ greps the current buffer. <leader>e and <leader>n are the kitchen-sink pickers when you do not remember which specific one you need. Previews render through bat in the rose-pine theme. - opens the parent directory in the builtin dir browser, Enter edits, - again goes up. For heavier file management drop to yazi with y in the shell, which cd's on exit. <leader>' flips to the alternate file for the edit/test or header/impl ping-pong, <leader>h searches help tags, <leader>k lists every keymap.

The edit loop

Completion is native and autotriggered: on an attached LSP buffer the menu pops as you type, nothing is preselected, typing fuzzy-filters in place. Walk entries with C-n/C-p and accept with Enter.

Renaming many spots is the 0.13 multicursor: Q adds a cursor on the word under the cursor, Q in visual mode cursors the selection, [count]Q drops a cursor on the next count matches, CTRL-L clears, gQ restores the last set. Edits on any cursor replicate everywhere. For a semantic rename prefer grn, which goes through LSP and catches references the parser understands.

Structural selection uses the treesitter text objects: v_an grows the selection to the next node up, v_in shrinks it, v_]N/v_[N jump between sibling nodes. gc comments lines or selections, za/zR/zM work folds since every filetype with a parser folds by syntax tree. inccommand=split gives live preview: type :%s/old/new and the split shows each match rewritten before you press Enter.

The LSP loop

Enabled servers attach by filetype automatically, no :LspStart. Native keys handle the quick moves: K hover, grn rename, gra code action, grr references, gri implementations, gO symbol outline, [d and ]d jump diagnostics, <C-W>d pops the diagnostic under the cursor. Leader pickers handle the rest with fzf previews: <leader>j definitions, <leader>v declarations, <leader>r references, <leader>i implementations, <leader>s document symbols, <leader>w live workspace symbols, <leader>\ the all-in-one finder on the symbol under the cursor, <leader>, and <leader>. call hierarchy, <leader>a code actions, <leader>b format the buffer.

Diagnostics stay quiet: pause on a line for one second and its message expands underneath as virtual text, then collapses when you move. That is updatetime 1000 plus virtual_lines.current_line. For the backlog, <leader>dd lists document diagnostics, <leader>dw the workspace. YAML gets schema-aware completion and validation for kubernetes manifests, docker-compose files, and GitHub workflows.

The git loop

Read-only inspection lives in nvim: <leader>gs status, <leader>gd diff, <leader>gl blame, <leader>gc commits, <leader>gh hunks. Anything that mutates belongs to lazygit (lg in the shell). The split keeps nvim buffers from fighting the index state.

Writing and documents

Typst: <leader>pt toggles the live preview, which re-renders in a browser pane on each keystroke. Markdown, HTML, and CSV use live-preview.nvim: <leader>ps starts, <leader>pc closes, <leader>; picks which preview to attach. Autosave writes, the preview re-renders, you never save manually.

Upkeep

<leader>u updates all 7 plugins and rewrites the deployed lockfile. After an intentional bump, copy the deployed nvim-pack-lock.json from nvim's config dir back to .config/nvim/ in the repo and commit, the lockfile is the pin mechanism, there are no version pins in init.lua. up in the shell covers everything else including nvim itself and treesitter parsers. <leader>x after any config tweak re-sources in place.

Keybinding	Action
-	Open parent directory (builtin)
<leader>q	Quit
<leader>x	Write and source
<leader>'	Alternate file
<leader>pt	Toggle Typst preview
<leader>ps	Start live preview
<leader>pc	Close live preview
<leader>;	Pick live preview
<leader>b	LSP format
<leader>u	Pack update
<leader>e	FzfLua global
<leader>n	FzfLua combine
<leader>/	Grep current buffer
<leader>z	Live grep native
<leader>f	Files
<leader>h	Help tags
<leader>k	Keymaps
<leader>l	Loclist
<leader>m	Marks
<leader>t	Quickfix
<leader>gf	Git files
<leader>gs	Git status
<leader>gd	Git diff
<leader>gh	Git hunks
<leader>gc	Git commits
<leader>gl	Git blame
<leader>gb	Git branches
<leader>gt	Git tags
<leader>gk	Git stash
<leader>\	LSP finder
<leader>dd	LSP document diagnostics
<leader>dw	LSP workspace diagnostics
<leader>,	LSP incoming calls
<leader>.	LSP outgoing calls
<leader>a	LSP code actions
<leader>s	LSP document symbols
<leader>w	LSP workspace symbols
<leader>r	LSP references
<leader>i	LSP implementations
<leader>o	LSP type definitions
<leader>j	LSP definitions
<leader>v	LSP declarations

---

Changelog

See CHANGELOG.md for version history and changes.

---

License

MIT