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 + OpenCode 2 via ~/.local/bin/oc2). Self-update via /updatefirstmate, not rebuild.
• OpenCode 2 is the firstmate primary. It is not a Homebrew formula: install @opencode-ai/cli@beta with Homebrew's npm (home.activation.opencode2). Launch through home/bin/oc2 so OPENCODE_CONFIG stays at home/.config/opencode2/opencode.json and cannot rewrite OpenCode 1.x's ~/.config/opencode. Do not add a brew opencode / opencode2 formula; zap would fight the npm install. firstmate harness detection matches *opencode*, so the opencode2 process name still classifies as OpenCode.
• Shell aliases: cc (Claude skip-permissions), co (Codex full-auto), gb (Grok --yolo), fm (firstmate via OpenCode 2), oc2 (OpenCode 2, isolated). 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.