dotfiles

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

Quick Start · Report Bug · Agent Skills

Features

• 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

Quick Start

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.

Usage

Day-to-day

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

Maintenance

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.

What’s installed

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)

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.

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.

Adding a new tool

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 if the package exposes zsh site-functions.

Adding a new dotfile

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 }}

Configuration

Chezmoi automation

These scripts run automatically on chezmoi apply:

AI tools

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.

Agent Skills

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

Managing skills

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

All skills

Quality & design (framework -> principles -> operational)

Scaffolding & setup

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

Workflow automation

AI & documentation

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

Subagents

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

License

Apache-2.0