dotfiles/AGENTS.md

Project notes for agents

Deliberate decisions in this repo - do NOT silently revert them:

• homebrew.onActivation.cleanup = "zap" in configuration.nix is intentional. It forces the good habit of declaring every Homebrew package in the Nix config instead of installing things ad-hoc, which keeps the machine reproducible. Do not soften it to uninstall or none. Users are warned about its effect; this note is for anyone tempted to change the setting itself.
• Agent configs under home/ are the source of truth. home.nix installs them with mkOutOfStoreSymlink + force = true, so edits to files in home/ apply live after the first rebuild that creates the symlink. Prefer editing those paths, not the live ~/.claude / ~/.grok / ~/.pi copies. rebuild.sh rotates stale *.backup files before switch so home-manager never fails with "would be clobbered".
• Grok Build is first-class here: home/.grok/config.toml and home/AGENTS.md (linked as ~/.grok/AGENTS.md). Claude, Codex, opencode, and Pi share the same home/AGENTS.md for multi-agent work.
• Pi is managed the same way: home/.pi/agent/{settings,models}.json, themes/, and custom extensions (terminal-status-title, calm). Do not symlink the whole ~/.pi/agent tree - sessions, auth, npm cache, and herdr's extensions/herdr-agent-state.ts stay live.
• firstmate lives at ~/Documents/firstmate as a mutable git clone (not in the Nix store). home.activation.firstmate clones it if missing and seeds config/backend=herdr + config/crew-harness=pi only when those files are absent. Launch with shell alias fm (cd + pi). Approve Pi project trust once so .pi/extensions/*.ts load. Self-update via /updatefirstmate, not rebuild.
• Shell aliases: cc (Claude skip-permissions), co (Codex full-auto), gb (Grok --yolo), fm (firstmate via Pi). They are intentional high-agency shortcuts.

Maintaining this file

Keep this file for knowledge useful to almost every future agent session in this project. Do not repeat what the codebase already shows; point to the authoritative file or command instead. Prefer rewriting or pruning existing entries over appending new ones. When updating this file, preserve this bar for all agents and keep entries concise.