AGENTS.md

Instructions for AI agents working with this dotfiles repository.

Repository Overview

This is a personal dotfiles collection for macOS/Linux. Configs are organized by tool in subdirectories (zsh/, vim/, git/, etc.) and installed via Makefile targets that copy files to $HOME.

Quick Reference

Build & Test Requirements

Dependencies for Testing

• zsh and bash - for syntax checking shell configs
• vint - for linting vim configs (pip install -r test-requirements.txt)
• eslint - for JavaScript linting (yarn install)

What Gets Tested

1. Shell scripts - Parsed with zsh --no-exec and bash -n for syntax errors
2. Vim configs - Linted with vint for style/correctness
3. JavaScript (dotjs/) - Linted with eslint using eslint/eslintrc.js
4. Setup scripts - All install/update scripts validated for shell syntax

CI

CircleCI runs make test against zsh 5.8.1 and 5.9. See .circleci/config.yml.

Directory Structure

Code Style Guidelines

Shell Scripts (zsh/bash)

• Must parse cleanly - zsh --no-exec <file> or bash -n <file>
• Scripts go in appropriate directory (git/ for git extensions, zsh/zshrc.d/ for modular zsh config)
• Git helper scripts use git-<name> naming convention (callable as git <name>)
• Use #!/usr/bin/env zsh or #!/usr/bin/env bash shebang
• Functions for reusable blocks in zsh/zshrc.d/functions.zsh
• Aliases in zsh/zshrc.d/aliases.zsh

Zsh Specifics

• Modular configs go in zsh/zshrc.d/*.zsh (auto-sourced)
• Use $HOME instead of ~ for portability in quoted strings
• Check for command availability with command -v <cmd> &>/dev/null before using

Vim/Neovim

• Vim (vim/vimrc): Uses vim-plug, must pass vint linting
• Neovim (nvim/init.lua): Lua-based, Kickstart.nvim structure with lazy.nvim
• Keep plugins organized by category with comments
• Use folding markers ({{{ / }}}) for vim config sections

JavaScript (dotjs/)

• ESLint config: eslint/eslintrc.js
• Parser: @babel/eslint-parser with ES6+ features
• Key rules:
  • No semicolons required (semi: 0)
  • Flexible quotes (quotes: 0)
  • No strict indentation (indent: 0)
  • Prefer dot notation (dot-notation: 2)
  • No eval or extending native prototypes
  • Wrap IIFEs (wrap-iife: 2)
  • Use curly braces (curly: 2)

Git Scripts

• Named git-<action> in git/ directory
• Installed to ~/.local/bin/ for git subcommand access
• Many use fzf for interactive selection (see git-fuzzy-* scripts)
• Must parse with zsh

General

• No trailing whitespace
• Match existing naming conventions
• Test changes with appropriate make test-* command
• Templated configs (like git/gitconfig.template) use {PLACEHOLDER} syntax

Making Changes

Adding a New Tool Config

1. Create directory: <tool>/
2. Add config files
3. Add Makefile target: install-<tool>
4. If applicable, add to install target dependencies
5. Add tests if shell scripts are involved

Modifying Existing Configs

1. Read the existing file to understand structure
2. Make changes following existing patterns
3. Run relevant tests: make test-<type>
4. If git config, update template and regenerate with git/setup

Adding Git Scripts

1. Create git/git-<name> with #!/usr/bin/env zsh
2. Make executable: chmod +x git/git-<name>
3. Run make test-zsh to verify syntax
4. Installed via make install-git to ~/.local/bin/

Adding Zsh Functions/Aliases

• Functions: Add to zsh/zshrc.d/functions.zsh
• Aliases: Add to zsh/zshrc.d/aliases.zsh
• Tool-specific: Create zsh/zshrc.d/<tool>.zsh

Common Patterns

Checking Command Availability

command -v nvim &>/dev/null && alias vim=nvim

Cross-Platform Detection

local uname=$(uname)
if [[ "$uname" == "Darwin" ]]; then
    # macOS
elif [[ "$uname" == "Linux" ]]; then
    # Linux
fi

Path Manipulation (zsh)

typeset -U path  # unique entries only
path=(/new/path "${path[@]}")

Conditional Homebrew Integration

if command -v brew &>/dev/null; then
    prefix="$(brew --prefix)"
    # use $prefix for paths
fi

Warnings

• Never commit secrets - Git config uses templates with placeholders
• Test before installing - make -n install shows what will happen
• Configs are copied, not linked - Changes to installed files won't sync back
• Some targets require sudo - tarsnap, system launchd configs

Debugging

• Shell syntax errors: Check line numbers in test output
• Vint errors: Follow vint suggestions, use --style-problem flag
• ESLint errors: Run yarn test-eslint directly for details
• Installation issues: Run make -n install-<tool> to see what will be copied