dotfiles: Instructions file for Codex

AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.

Repository Overview

This is a personal dotfiles repository for managing user configuration files across macOS systems. It uses GNU Stow for symlink management and Homebrew for tool installation.

Architecture Philosophy:

• Simple and maintainable over complex abstractions
• Transparent symlink management (no templates)
• Monolithic configuration files (single .zshrc)
• Tool-centric directory structure

Repository Structure

dotfiles/
├── .gitignore              # Excludes IDE/OS files
├── .stowrc                 # Stow configuration (dir=configs, target=$HOME)
├── .githooks/
│   └── pre-commit          # gitleaks secret scan on staged changes
├── .github/
│   └── workflows/
│       └── gitleaks.yml    # CI secret scan on push/PR
├── Brewfile                # Homebrew packages and casks (single source of truth)
├── install.sh              # Tool installation via Homebrew
├── bootstrap.sh            # Config deployment via Stow
├── README.md               # User-facing documentation
├── AGENTS.md               # This file
├── LICENSE                 # Unlicense (public domain)
├── lib/
│   └── menu.sh             # Shared confirmation prompt library
└── configs/                # Tool configurations (stow packages)
    ├── zsh/
    │   └── .zshrc             # Shell config (~150 lines)
    ├── git/
    │   ├── .gitconfig         # Git settings
    │   └── .gitignore_global  # Global ignores
    ├── vim/
    │   └── .vimrc             # Minimal Vim config
    ├── ghostty/
    │   └── .config/ghostty/config
    ├── k9s/
    │   └── .config/k9s/config.yaml
    └── mise/
        └── .config/mise/config.toml

Setup Workflow

The repository provides a two-step setup process:

1. ./install.sh - Installs tools via Homebrew
   • Detects platform (macOS only currently)
   • Prompts [Y/n] for each tool (Enter = yes, n = skip)
   • Installs Homebrew if missing
   • Installs packages: stow, k9s, kubectl, kubectx, helm, kind, ko, oras, kluctl, awscli, gh, jq, yq, ncdu, git, go, mise, gitleaks
   • Installs casks: ghostty (terminal emulator), raycast (productivity launcher), cursor (AI code editor), codex (OpenAI coding agent CLI), docker (Docker Desktop)
   • Installs Rust via rustup
   • Installs oh-my-zsh with plugins (zsh-autosuggestions, zsh-syntax-highlighting)
   • Installs nvm and Node.js LTS
   • Installs Claude Code via npm
   • Configures this repo's pre-commit hook (core.hooksPath=.githooks) for gitleaks scanning
   • Idempotent (safe to re-run)
   • --all flag skips prompts (installs everything)