AGENTS.md

@AGENTS.local.md

Personal dotfiles managed by coding agents via Chezmoi. Targets macOS (darwin) and Fedora Linux. See docs/vision.md and docs/core-principles.md for the philosophy behind this setup.

The Stack

What it feels like: Ghostty launches into tmux, tmux runs zsh with Starship prompt, Neovim is the editor. Vim keybindings work everywhere — shell, multiplexer, editor. Navigation between tmux panes and Neovim splits is seamless via tmux-navigator.

Repo Map

home/                  # All managed dotfiles (Chezmoi source)
  dot_config/          #   -> ~/.config/
  dot_claude/          #   -> ~/.claude/ (user-scope skills, agents, settings)
  dot_local/bin/       #   -> ~/.local/bin/
  private_dot_ssh/     #   -> ~/.ssh/
  private_Library/     #   -> ~/Library/ (macOS only)
bin/                   # Repo scripts: setup, test, sync-claude-*
test/                  # BATS test suite
docs/                  # Architecture docs; decisions in docs/adrs/
.claude/               # Project-scope agent config (this repo only)
  skills/              #   Project slash-commands
  hooks/               #   Pre/post tool hooks
  agents/              #   Subagent definitions
hk.pkl                 # Lint/format hooks (pre-commit, pre-push, CI)
mise.toml              # Dev tool pins + `mise run` tasks

How to Work Here

The One Rule

Edit in home/, never in ~ or ~/.config/. Chezmoi owns the home directory — destination edits get overwritten on next apply.

Change Workflow

1. Edit source files in home/
2. chezmoi diff — review; only your changes should appear
3. chezmoi apply [target ...] — apply (selectively if diff shows unrelated changes)
4. chezmoi status — confirm clean state
5. Verify in a tmux PTY when touching shell/terminal config:

tmux new-session -d -s verify -x 200 -y 50 "zsh -l"
sleep 2 && tmux capture-pane -t verify -p
tmux kill-session -t verify

Commands

./bin/setup             # Bootstrap dev tools via mise
./bin/test              # Run all tests (what CI runs)
bats test/<file>.bats   # Run one test file
mise run lint           # Lint + auto-fix (hk fix)
hk check                # Lint without fixing (what CI runs)

Before opening a PR: hk check && ./bin/test

hk also runs automatically on pre-commit and pre-push — it stashes unstaged changes, auto-fixes, and enforces conventional commit messages. See hk.pkl.

Skills

Two scopes, two sources — edit the source, never ~/.claude/:

• User (available everywhere): home/dot_claude/skills/ → ~/.claude/skills/ on apply
• Project (this repo only): .claude/skills/

Most-used:

Browse the two dirs above for the full set (~35 skills).

Change Hygiene

• Pin versions — every dependency gets an exact version; Renovate handles updates
• Prefer mise / /install — add tools, plugins, and MCP servers via /install; ad-hoc installers (npx/pipx/pip install/npm -g/…) are blocked by a guard hook, so don't reach for them. See docs/claude-code.md
• One change per commit — small, conventional commits via /commit
• Package Manager subagent — use for version conflicts, container images, bulk updates, or GitHub Actions digests (see docs/renovate.md)

Deep Dives

Where to Look First

• Add a tool: /install <name> — it handles everything
• Fix a broken Neovim plugin: /nvim
• Understand a config file: Read the source in home/ — templates use Go text/template (.chezmoi.os, lookPath)
• Platform-specific logic: Check .chezmoiignore and .tmpl files for {{ if eq .chezmoi.os "darwin" }} guards
• Morning catchup: /update merges Renovate PRs and applies changes
• Chezmoi internals: docs/agents/chezmoi.md covers templates, scripts, prefixes, and troubleshooting