Dotfiles

macOS developer environment managed with chezmoi. Optimized for software engineering, data infrastructure, AI engineering, and a Codex-centered workflow.

Apple Silicon macOS is the only supported target. Machine-specific behavior is handled through capability probes rather than OS branches.

Stack

• Core: zsh, chezmoi, Homebrew
• Primary agent: Codex in the ChatGPT desktop app
• Agent fallbacks: Codex CLI in cmux; Claude Code when explicitly needed
• Review: Codex desktop first, VS Code for visual inspection
• Terminal: cmux, Ghostty, iTerm2, tmux, Powerlevel10k, fzf, zoxide
• Editor: VS Code and Neovim
• Python: uv
• Infrastructure: OrbStack, direnv, gh, difftastic, lazygit
• Productivity: Raycast, Obsidian, Todoist, KeepingYouAwake

Installation

1. Install Xcode Command Line Tools:

   xcode-select --install

2. Bootstrap and apply:

   sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply k-schmidt

3. Sign in to the ChatGPT desktop app, then authenticate terminal tools as needed:

   gh auth login
   codex login
   claude auth login

4. Configure Touch ID for sudo if desired:

   sudo sed -i '' '2i\auth       sufficient     pam_tid.so' /etc/pam.d/sudo

Workflow

Codex desktop is the control plane. A task owns one coherent outcome; a managed worktree provides isolation when implementation should not touch the local checkout. Use Codex handoff to move a task between its worktree and the local checkout.

cmux remains available for terminal-first Codex CLI sessions. Its Codex hooks provide lifecycle state, notifications, and session restoration. VS Code is the fallback review surface for diffs that benefit from a full editor. Claude remains an explicit fallback: cmux keeps its native Claude wrapper for those sessions, but no shell alias or launcher makes Claude the default.

Implementation tasks stop at a tested, review-ready diff. Commit, push, and pull-request creation happen only after explicit approval.

Codex skills

Stable cross-project skills live in ~/.agents/skills and are shared with Claude through a compatibility link. Codex defaults to one task and decides implementation structure from the work rather than requiring a planning pipeline.

• $to-prd creates a concise specification when a persistent PRD is actually useful; it does not force task decomposition.
• $diagnosing-bugs establishes a tight reproduction, tests falsifiable hypotheses, and stops at root cause unless a fix was requested.
• $ast-grep searches and rewrites code structurally when shape matters more than text.
• $review-before-publish reviews correctness, repository standards, and specification fidelity across committed and uncommitted changes without crossing the publish boundary.
• $dotfiles manages chezmoi source, application, and synchronization.
• $unslop is an explicit-only editor for removing generated-writing patterns from human-facing prose.

Project-specific workflows live in a non-discovered library and can be copied into a repository when needed:

codex-skill list
codex-skill attach grill-with-docs update-docs

The command installs versionable snapshots under the repository's .agents/skills/ directory and refuses to overwrite existing skills. grill-with-docs runs a domain-aware design interview; update-docs reconciles implemented behavior with project documentation. Both remain explicit-only after attachment.

Editing

Always edit source files rather than deployed targets:

chezmoi edit ~/.zshrc
chezmoi apply

To add a Homebrew package:

chezmoi edit ~/.config/brew/Brewfile
chezmoi apply

Publishing remains explicit:

cd ~/.local/share/chezmoi
pre-commit run --all-files
git add .
git commit -m "feat: description"
git push

Chezmoi installs commit and push hooks automatically. Commit checks cover portable file syntax, staged secrets, skill metadata and links, rendered shell sources, Neovim Lua formatting, and a full chezmoi dry run. The push hook scans the complete dotfiles Git history for secrets before anything leaves the machine.

Ownership

• dot_codex/AGENTS.md — portable global guidance loaded by Codex
• AGENTS.md — repository-only chezmoi rules; excluded from deployment
• dot_agents/skills/ — canonical global personal skill source shared across agents
• dot_local/share/codex-skill-library/ — reusable skills attached to projects only when needed
• dot_local/bin/executable_codex-skill — helper for listing and attaching project skills
• dot_claude/ — minimal Claude fallback import and settings
• dot_config/brew/Brewfile — Homebrew formula and cask manifest
• dot_config/cmux/ — cmux editor and agent-integration settings
• dot_zshrc, dot_bashrc, dot_bash_profile — shell configuration
• dot_config/nvim/ — Neovim configuration
• .pre-commit-config.yaml — repository-only validation and secret checks
• run_onchange_*.sh.tmpl — idempotent package and integration reconciliation

Codex desktop owns ~/.codex/config.toml, authentication, plugins, MCP servers, project trust, hooks state, and runtime databases. VS Code Settings Sync owns VS Code settings, keybindings, and extensions. Neither mutable surface is tracked here.

Optional capabilities

• Optional tools are activated only when their executable or directory exists.