dotfiles

Imported from valbeat/dotfiles (AGENTS.md). Install upstream with npx skills add valbeat/dotfiles. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

• Core dotfiles live at repo root (.zshrc, .vimrc, .gitconfig, .tmux.conf, etc.). Each is symlinked into $HOME by home-manager (darwin/home.nix); new root dotfiles must be added to its dotfiles list. That list is for files and for directories this repository owns outright (.vim); a directory shared with other tools goes in configFiles or agentFiles instead, entry by entry.
• agents/AGENTS.md is the user-level instruction file, shared by all three agents and in effect in every project. darwin/home.nix links that single file to ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md and ~/.gemini/GEMINI.md (globalInstructions), so there is nothing to keep in sync: edit it once. It is structured as a common section plus one section per agent, each of which is told to follow only its own.
• It must never be moved to ./CLAUDE.md or ./.claude/CLAUDE.md. Claude Code would then read it as this repository's project instructions and stop falling back to AGENTS.md — the same trap as #154.
• This file (AGENTS.md at the root) is the project instruction file, and the only one; Claude Code reads it directly (v2.1.277+). That fallback applies only while no ./CLAUDE.md, ./.claude/CLAUDE.md or CLAUDE.local.md exists, so never add one here.
• .claude/ holds the files this repo owns for Claude Code: agents/, hooks/ and statusline.sh (skills do not live here, see below). darwin/home.nix links those files individually into ~/.claude, ~/.codex and ~/.gemini, which are real directories holding each tool's runtime state (sessions, plugins, logs); never link the directories themselves, and tools/migrate-agent-dirs.sh converts an old whole-directory link. Everything else under them is runtime state and untracked. .codex/ and .gemini/ no longer hold tracked files — Codex custom prompts are deprecated, so Codex gets its skills from the plugin marketplaces instead.
• .config/ is the same case and uses the same rule: ~/.config is shared with every XDG-following tool (gh, gcloud, fish, karabiner, git, ...), so home.nix links only the entries this repo owns (configFiles), never ~/.config itself. Linking the directory hides every unmanaged entry — home-manager moves the real one to ~/.config.hm-backup — and those tools silently lose their configuration and credentials. New entries go in both configFiles and the .config/* allow-list in .gitignore. MIGRATE_DIRS=.config tools/migrate-agent-dirs.sh converts an old whole-directory link.
• darwin/ holds the nix-darwin configuration: configuration.nix (entry), system-defaults.nix (macOS defaults), home.nix (dotfile symlinks), homebrew.nix (taps/brews/casks), and claude.nix + claude/merge.jq (managed keys of the Claude Code / Antigravity CLI settings.json).
• darwin/orca.nix applies the Orca automation definitions from the private flake input orca-automations (valbeat/orca-automations) at activation. That repository is the single source of truth: never change automations only in Orca. Changes made in Orca (the app, another agent) must be written back with its scripts/export.sh and merged; otherwise apply stops with a conflict and leaves Orca untouched. After merging there, run nix flake update orca-automations here and switch. Each host also declares an orcaHostRole (flake.nix, written to ~/.local/state/orca-automations/role and passed to apply.sh): definitions name the roles they run under and only the matching ones reach that Mac's Orca, so a second machine does not fire the same PR-opening automation twice. A new host runs nothing until it is given a role.
• flake.nix wires it together and exposes every command as an app: build / switch / update (system) and test / settings-diff / patches / hunk-skill (repo tasks, formerly the Makefile). Vim-related assets sit under .vim/ (plugins, colors, rc snippets).
• tools/ keeps the non-nix helpers: patches/ (plugin-cache patches), settings-diff.sh, and tests/ (test-*.sh). They are run through the flake apps (nix run .#test and friends); there is no Makefile.

Build, Test, and Development Commands

• nix run .#build: dry-run build of the darwin system; CI runs this on every PR. Run it after touching darwin/ or flake.nix.
• nix run .#switch: fetches inputs as the invoking user first (the private orca-automations input needs the user's SSH key), then builds and activates (system defaults + symlinks + Homebrew + settings.json merge; runs as root). An agent can run it only after the user runs sudo -v in a real terminal: the sudo timestamp is shared per user for 15 minutes (darwin/configuration.nix). Ask for that instead of handing the command back, and run it by the expanded absolute path (nix run /Users/<user>/src/github.com/valbeat/dotfiles#switch; the allowlist in darwin/claude.nix matches that exact text, not ~ or .#switch) so the flake in the current directory is never the one activated.
• nix run .#update: pulls latest main and updates git submodules. The public flake inputs (nixpkgs, nix-darwin, home-manager) are updated by .github/workflows/flake-update.yml every Monday as a pull request; orca-automations is private and updated locally with nix flake update orca-automations.
• nix fmt: formats all .nix files with nixfmt; CI fails on unformatted files (nix fmt -- --ci) and also runs nix flake check --no-build.
• nix run .#test: runs tools/tests/test-*.sh (settings merge, settings-diff, agent-dir migration). When changing merge.jq, update the test first — and git add a brand-new test file before running, see Gotchas.
• nix run .#settings-diff: shows which managed keys the next switch would reset in ~/.claude/settings.json and ~/.gemini/antigravity-cli/settings.json.
• nix run .#patches: applies the claude -p replacement patches to plugin caches (idempotent; rerun after a plugin update overwrites them).
• nix run .#hunk-skill: re-syncs the vendored hunk-review skill into agent-plugins-private after brew upgrade hunk (then bump portable-tools and ship it). PLUGINS_PRIVATE overrides the destination checkout.

Claude Code / Codex Settings

• ~/.claude/settings.json, ~/.gemini/antigravity-cli/settings.json, and ~/.codex/config.toml are untracked: the tools write runtime state into them (/model, /config, auto mode, plugin installs, Orca's agent-status hooks), and committing them would leak machine- and project-local data into this public repo.
• Intended settings (permissions, own hooks, enabledPlugins, UI preferences) go in darwin/claude.nix; nix run .#switch merges them into the live files via darwin/claude/merge.jq (managed keys win, unnamed keys pass through, hooks are unioned). model is deliberately not managed.
• A managed key changed locally via /config or claude plugin install is reset on the next switch. Check nix run .#settings-diff first and port anything worth keeping to darwin/claude.nix.
• Skills never live in this repo. They live in the valbeat/agent-plugins-private (default; environment-coupled and experimental) and valbeat/agent-plugins (public; generalized) marketplaces and are invoked with a namespace (/personal-tools:review, /git-workflow:commit). Codex reads the same marketplaces: agent-plugins-private lists only portable-tools (skills that are safe outside Claude Code) in .agents/plugins/marketplace.json, which Codex prefers over .claude-plugin/marketplace.json; everything else stays Claude-only. Update Codex with codex plugin marketplace upgrade. Placement rules and the inventory procedure are in /skill-management:skill-inventory. To update one: edit the marketplace repo (~/src/github.com/valbeat/agent-plugins{,-private}), bump version in plugin.json (an unchanged version is skipped), push, then run claude plugin marketplace update and claude plugin update.

Gotchas

• The flake apps run the repo's files as git sees them: a modified tracked file is picked up without committing, but a file that is still untracked is not in the flake source at all. git add a newly created test or tool before nix run .#test / nix run .#patches, or it is silently skipped.
• CI does not fetch the private orca-automations input: nix run .#build there overrides it with ci/orca-automations-stub. Locally, reproduce the CI check with nix run .#build -- --override-input orca-automations "path:$PWD/ci/orca-automations-stub".
• Switching branches rewrites the live Claude/Codex/Gemini config. The linked files (agents/AGENTS.md, .claude/agents/, .claude/hooks/, .claude/statusline.sh) resolve into this checkout, so git checkout swaps them for every running session. Runtime state is no longer affected: it lives under $HOME, outside this repository. Do branch work in a worktree, never switch during --loop or long autonomous runs, and confirm git branch --show-current before committing (another session may have switched the shared checkout). Push explicitly with git push origin <branch>.
• Checking out a stale main that still tracked settings.json overwrites the live file, and the following git pull deletes it. Run git fetch first, check git diff --stat HEAD..origin/main -- .claude/settings.json .gemini/settings.json, and copy ~/.claude/settings.json aside before moving.
• .claude/hooks/guard.sh blocks any Bash command whose text matches claude -p / claude --print, including an echo or grep that merely contains it. Search with a different token, or prefix CLAUDE_ALLOW_PRINT=1 when the call is intended.

Coding Style & Naming Conventions

• Shell/Vim config: prefer POSIX-compatible snippets and two-space indentation to match the existing style; keep per-tool settings in their own rc file and follow the current plugin manager/layout.
• Keep filenames dot-prefixed and aligned with $HOME paths; guard a platform-specific variant with the .gitconfig.osx pattern instead of inventing new suffixes.

Testing & Review

• The verification commands are in the section above: nix run .#build after darwin/ or flake.nix, nix run .#test after tools/ or merge.jq, nix fmt after any .nix edit. CI enforces all three on PRs.
• Spot-check a representative link after a switch (ls -l ~/.zshrc must resolve into this repo). For Vim tweaks, launch vim once to confirm no startup errors.
• Rebase onto main before opening a PR, and give the description a summary, any new command or env var, and the verification steps actually run. Commit message, branch and PR conventions are the global ones in agents/AGENTS.md.

Security

• Never commit machine-specific secrets or tokens: use env var references or a .gitconfig.local-style override kept out of version control. Keep a new tool's defaults secure (gpg, SSH) and note any required permissions or key locations in a comment next to the config they affect.