dotfiles

Cross-platform dev environment powered by Chezmoi + Homebrew. One command to a fully configured machine.

Quick Start · Report Bug · Agent Skills

• Homebrew + apt as source of truth for CLIs (git, gh, kubectl, terraform, ...)
• Per-language version managers: fnm (Node), uv (Python), rustup (Rust)
• Pinned upstream installers for tools that need it: gcloud, aws-cli, Snowflake Cortex
• Zsh with Oh My Zsh + Powerlevel10k and pre-generated completions
• Tmux with Ctrl+a prefix, vim keys, Catppuccin cyberdream theme
• Ghostty terminal with cyberdream theme and MonaspiceNe Nerd Font
• Neovim (HEAD) with LSP for all included languages
• AI agents (Claude Code, Antigravity, Codex, Copilot) auto-installed via chezmoi
• A portable agent skills catalog in dot_agents/skills/ and subagents in dot_agents/agents/, installable into any tool via agentspec. See Agent Skills for the full list.
• Chezmoi automation scripts that trigger on apply
• Docker cleanup launchd agent running daily at 3 AM

One-liner (installs Homebrew + chezmoi, then runs chezmoi init --apply):

curl -fsSL https://raw.githubusercontent.com/urmzd/dotfiles/main/install.sh | bash

Or step by step:

# 1. Install Homebrew (macOS) or your distro's package manager (Linux)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Install chezmoi and apply this repo in one shot
sh -c "$(curl -fsLS https://get.chezmoi.io)" -- init --apply urmzd

chezmoi apply installs Brewfile/apt packages, sets up gcloud/aws/cortex from upstream, and installs the AI CLIs. Open a new terminal afterwards.

chezmoi diff          # Preview pending dotfile changes
chezmoi apply         # Apply dotfile changes to $HOME
chezmoi add <file>    # Start tracking a new file
chezmoi edit <file>   # Edit source, then apply

dotfiles apply           # Preview diff, confirm, then apply  (-y skips confirm)
dotfiles diff            # Preview pending chezmoi changes
dotfiles edit            # Open dotfiles source in editor
dotfiles config          # Re-run chezmoi prompts to pick up new/changed flags

dotfiles update          # Everything: brew packages + AI CLIs, then apply
dotfiles update packages # brew upgrade + apply
dotfiles update groups   # Toggle package groups + excludes (fzf), then apply
dotfiles update ai       # Reinstall AI CLIs at pinned versions

dotfiles doctor          # chezmoi doctor + tool versions + documentation hygiene
dotfiles status          # Show installed AI tool versions
dotfiles clean           # Prune build artifacts and caches

Run dotfiles config after pulling changes that add new prompts (like the package flags), then dotfiles update groups any time to fine-tune which groups install without hand-editing chezmoi.toml.

CLI essentials (Homebrew on macOS, apt/dnf/pacman on Linux): git, gh, fzf, ripgrep, jq, yq, just, tmux, direnv, chezmoi, tree-sitter, uv, tealdeer, terraform, kubectl, helm, k9s, colima, docker, fnm, deno, go, lua, ...see Brewfile.tmpl.

Version managers (per-language, best-in-class): fnm (Node), uv (Python), rustup (Rust).

Upstream-pinned installers (security/auth fixes ship faster than distro repos):

• gcloud + aws-cli, run_onchange_after_install-cloud-clis.sh.tmpl
• Snowflake Cortex Code, run_onchange_after_install-cortex.sh.tmpl (gated on install_cortex feature flag)
• gh CLI extensions, run_onchange_after_install-gh-extensions.sh.tmpl (github/gh-stack for stacked PRs)

Package selection is prompt-driven. chezmoi init asks for a package_preset (minimal = core CLI + editor, standard = + cloud/infra + fonts, full = + mobile dev), which sets defaults for the per-group toggles below. Each group can be overridden independently, and pkg_exclude drops individual packages by name.

The last two sit off the preset ladder on purpose, including full. Both are heavy (llvm alone, pulled in by zig, is over a gigabyte; Temporal is roughly 153 MB) and neither is something this setup reaches for by default, so they have to be asked for by name.

Set any of these at init or in ~/.config/chezmoi/chezmoi.toml, then re-run chezmoi apply. The Brewfile installer continues past individual package failures, retries the remainder once, and prints categorized next steps (tap, permission, unknown formula, network, conflict) rather than aborting the whole apply.

AI tools (installed via run_once_after_install-ai-clis.sh.tmpl, sentinel-gated): Claude Code, Codex (workspace-write "Auto" default with writer/reviewer/plan/guardian profiles), Antigravity CLI (agy, self-updating), GitHub Copilot. Update with dotfiles update ai.

1. Homebrew: add to Brewfile.tmpl. Linux: add to the apt/dnf/pacman list in run_once_before_install-packages-v2.sh.tmpl.
2. For tools needing version pinning: write a run_onchange_after_install-<name>.sh.tmpl mirroring the cortex / cloud-clis pattern.
3. Run chezmoi apply. Completions regenerate automatically, but check which of the three shapes the tool needs first:
   • Ships its own _<tool> into Homebrew's share/zsh/site-functions. Nothing to do, and run_onchange_after_z-generate-completions.sh.tmpl deliberately skips generating a rival copy, since Homebrew's tracks the installed formula version.
   • Has a <tool> completion zsh subcommand but no site-functions. Add a generate_completion line. Output goes to ~/.zsh/completions/ and is autoloaded lazily, so it costs nothing at shell startup.
   • Is bash-style (complete -C / complete -F, as with aws and npm) or otherwise needs compdef. It has to be appended to ~/.zsh/completions-post.zsh instead, which ~/.zshrc sources after compinit. A file placed in fpath without a leading #compdef line is never bound to any command and silently completes nothing.

1. Create or edit the file in your home directory
2. Run chezmoi add <file> to start tracking it
3. Use dot_ prefix naming, private_ for sensitive files, .tmpl for templates
4. Platform-specific blocks use {{ if eq .chezmoi.os "darwin" }}...{{ end }}

These scripts run automatically on chezmoi apply:

AI coding agents are installed by chezmoi apply (sentinel-gated, no shell-startup cost). Check versions with:

dotfiles status

Per-tool AI config is tracked and deployed by chezmoi:

Codex runs OpenAI's documented "Auto" preset by default: sandbox_mode = "workspace-write" + approval_policy = "on-request", with the guardian auto-reviewer (approvals_reviewer = "auto_review") classifying every escalation before it reaches you. Drop to codex --profile reviewer or --profile plan for read-only work; the guardian profile supervises orchestrate-agents fleets.

Skills and subagents in this repo are cross-project: once installed via agentspec, they are available to any tool (claude-code, codex, gemini, copilot) from any project. The source-of-truth lives in dot_agents/skills/ and dot_agents/agents/, following the Agent Skills Specification.

Related standards: AGENTS.md and llms.txt

All skills are installed automatically via chezmoi apply. The install-skills script uses agentspec to install both local skills from dot_agents/skills/ and third-party skills globally to all agents:

To manage skills and agents manually:

agentspec manage list                          # List managed resources with tool linkage
agentspec manage add <source>                  # Add from local path, GitHub (owner/repo), or name
agentspec manage link <name> <tool>            # Link resource to a tool (claude-code, codex, etc.)
agentspec manage remove <name>                 # Remove a managed resource
agentspec manage create [name]                 # Scaffold a new resource
agentspec manage validate [path]               # Validate SKILL.md or agent definition
agentspec status                               # Show managed vs unmanaged inventory
agentspec sync --fast                          # Discover, adopt, link, and verify all resources

scaffold-project is the canonical source for standard files; each scaffold-<lang> adds only language-specific deltas.

create-oss-skill owns the base spec; extend-oss-skills-to-claude is a sequel covering only the Claude-specific deltas.

Delegation targets in dot_agents/agents/ that adopt a specific reasoning mode. Installable into any tool via agentspec manage link <name> <tool>.

Apache-2.0