Dotfiles Multiplataforma Nativos para Agents
ggkguelensan/dotfiles
Dotfiles agent-ready para Windows, WSL2 e macOS com chezmoi
Ver no GitHubRepositório de configurações cross-platform (Windows + WSL2 + macOS) gerenciado por chezmoi, design agnóstico para Claude Code com skills integradas e documentação de princípios. Sincroniza VS Code, terminal (Ghostty/tmux), shells (zsh/p10k) e automações via um único repo com roteamento per-OS.
Instalação
npx convez-ai ggkguelensan/dotfiles1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Bootstrapping automático de máquinas via Claude Code
- Sincronização de configurações entre Windows, WSL e macOS
- Roteamento inteligente de mudanças de config por camada e sistema operacional
- Documentação de decisões arquiteturais em princípios e layer-map
Veredito

Solução sofisticada e bem-documentada para quem trabalha com ambientes multi-OS e quer automação nativa de agents. Exige familiaridade com chezmoi, templates e topologias de terminal, mas oferece padrão sólido e reproducível.
README
A tradução para o português deste README ainda está na fila.
dotfiles
Agent-native, cross-platform dotfiles for Windows + WSL2 Ubuntu + macOS, managed by
chezmoi. One repo, three operating systems: each machine runs its own
independent chezmoi instance of the same repo, and per-OS routing in
home/.chezmoiignore.tmpl decides which files apply where.
The repo is designed to be opened by Claude Code: it carries small skills
(.claude/skills/) and principle docs (docs/) so an agent can bootstrap a machine, route a
config change to the correct layer, sync local drift back, and explain why the configuration
is the way it is.
Bootstrap
Three independent chezmoi instances of the same repo — run the bootstrap on each OS (Windows and WSL are two separate instances on the same physical machine).
Windows (PowerShell):
winget install twpayne.chezmoi
chezmoi init --apply ggkguelensan/dotfiles
WSL2 Ubuntu / Linux / macOS:
sh -c "$(curl -fsLS get.chezmoi.io)" -- -b ~/.local/bin && ~/.local/bin/chezmoi init --apply ggkguelensan/dotfiles
On first run chezmoi prompts once for the git email (default gkguelensan@gmail.com) and
detects WSL automatically.
Or let an agent do it: open this repo in Claude Code and run the dotfiles-setup skill — it bootstraps, applies, and verifies the machine.
Repo map
| Path | What it is |
|---|---|
home/ | chezmoi source state (.chezmoiroot points here; repo root stays clean for docs/skills) |
home/.chezmoi.toml.tmpl | machine config template — defines template data .email, .wsl |
home/.chezmoiignore.tmpl | per-OS routing (what not to apply on a given OS) |
home/.chezmoiexternal.toml | pulls ~/.claude/statusline.sh from claude-code-statusline |
home/.chezmoitemplates/ | shared VS Code settings/keybindings templates, included by per-OS targets |
home/dot_config/ghostty/config | Ghostty terminal — one XDG file serves macOS and Linux; cmux inherits it for rendering |
home/dot_config/cmux/cmux.json | cmux app settings (macOS-only; JSONC by design) |
docs/principles.md | configuration philosophies and decision vectors |
docs/layer-map.md | the precedence ladder, setting scopes, and the routing table ("where does this setting go?") |
docs/agent-supervision.md | attention stack, terminal topologies, persistence, node/fnm notes |
docs/fonts.md | full-glyph font install per OS (MesloLGS NF links, brew casks, the "fonts install client-side" rule) |
.claude/skills/dotfiles-setup/ | bootstrap/verify a machine |
.claude/skills/dotfiles-update/ | route a config change to the right layer |
.claude/skills/dotfiles-sync/ | pull local drift back into the repo and commit |
.claude/skills/dotfiles-help/ | teach the principles behind the config |
CLAUDE.md | agent working agreement for this repo |
Per-OS routing summary
- Windows only:
AppData/**(VS Code user settings/keybindings),.wslconfig, the PowerShell extension-install script. - macOS only:
Library/**(VS Code user settings/keybindings),.config/cmux/**. - WSL only:
.vscode-server/data/Machine/settings.json(the Remote-WSL machine layer — Settings Sync never touches it; this repo is its only backing store). - Unix only (WSL/macOS):
.zshrc,.p10k.zsh,.tmux.conf,.claude/**,.config/ghostty/**,~/.local/bin/agent-notify, the shell extension-install script. Claude Code hooks are unix-only in this repo for now, so nothing under.claude/is applied on Windows (Ghostty has no Windows build either).
Manual post-steps
Things the repo cannot automate — the dotfiles-setup skill walks through verifying each:
- MesloLGS NF font — install on the host OS (Windows/macOS) so powerlevel10k renders in VS Code/terminals. Direct TTF links and per-OS commands: docs/fonts.md.
- WSL clock resync scheduled task (Windows) — the WSL2 clock drifts after host sleep and
breaks TLS/auth for agents. Create a Scheduled Task: trigger on Event Log
System/Microsoft-Windows-Power-Troubleshooter/ Event ID 1 (resume), actionwsl.exe -u root -- hwclock -s. - System node symlinks in WSL — fnm's multishell symlinks live on tmpfs and die on WSL
restart; non-interactive processes (hooks, MCP servers, sidecars) need a durable node:
sudo ln -s ~/.local/share/fnm/node-versions/<LTS>/installation/bin/{node,npm,npx} /usr/local/bin/. /etc/wsl.conf— set[interop] appendWindowsPath=false(keeps 35/mnt/cdirs out of$PATH; keepenabled=trueforpowershell.exe/toasts), thenwsl --shutdown.- inotify limits in WSL — many worktrees exhaust default watch limits:
printf 'fs.inotify.max_user_watches=1048576\nfs.inotify.max_user_instances=512\n' | sudo tee /etc/sysctl.d/60-inotify.conf && sudo sysctl --system. - Windows toasts from WSL — install BurntToast (
Install-Module BurntToast -Scope CurrentUserin PowerShell) or dropwsl-notify-send.exeinto the path;agent-notifyuses whichever is available. - Claude bell channel (WSL/VS Code machines) —
claude config set --global preferredNotifChannel terminal_bell(writes~/.claude.json, not chezmoi-managed). On macOS leave it atauto: Ghostty shows Claude's OSC notifications natively. - macOS terminals —
brew install --cask ghostty; cmux:brew tap manaflow-ai/cmux && brew install --cask cmux+ CLI symlink (sudo ln -sf "/Applications/cmux.app/Contents/Resources/bin/cmux" /usr/local/bin/cmux). Both read~/.config/ghostty/config; grant Ghostty Notifications permission once.
Daily cycle
- Edited the live config (settings UI, tweaked
~/.zshrc, ...):chezmoi re-add(or inspect first withchezmoi diff), then commit in~/dotfiles. The dotfiles-sync skill automates this. - Edited the repo source (
home/...):chezmoi diff, thenchezmoi apply. - New setting and unsure where it belongs: consult
docs/layer-map.mdor run the dotfiles-update skill. - Pull changes made on another machine:
chezmoi update(git pull + apply).
Caveats
.wslconfigmemory cap is sized for a ~32GB host (memory=20GB≈ 60%); adjust per machine and runwsl --shutdownto apply.- Externals respect
.chezmoiignore: since.claude/**is ignored on Windows, the statusline external is only fetched on unix machines. If a chezmoi version ever fetches it on Windows anyway, ignore the stray file — it is unused there. - Strict JSON: all generated VS Code/Claude JSON files contain no comments or trailing
commas by design; the explanations live in
docs/layer-map.md. The single exception ishome/dot_config/cmux/cmux.json— cmux documents JSONC support, so it carries comments. - Three instances drift independently — run
chezmoi updateon each OS after pushing changes from one of them.