dotfiles: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. The README covers the layers, rebuild, update and Stow commands:

@README.md

Core Commands

• Nix rebuild: ask user to run this, NEVER run it yourself
• Nix validation: nix flake check or nix flake check --all-systems
• Nix builds: nix build .#darwinConfigurations.<host>.system on Darwin (zap, plumbus); nix build .#nixosConfigurations.<host>.config.system.build.toplevel on NixOS (rpi5-homelab, renoir, wily) — NixOS has no .system attribute
• wily's private submodule: a .# flake leaves submodules out, checked out or not, and configuration.nix skips the private submodule when absent, so such a build passes without the work config. When a change could interact with it, build '.?submodules=1#nixosConfigurations.wily.config.system.build.toplevel' (as nh's flake does); in a git worktree, run git submodule update --init nix/hosts/<host>/<submodule> first
• Format Nix files: nix fmt (uses nixfmt-rfc-style)
• CI testing: Follow .github/workflows/test.yml workflow
• Toolchain outside Neovim: language toolchains (go, python3, node, ruby, rustup, elixir, tree-sitter, ...) are NOT on the base PATH — stow/shared/.shell/bin/nvim injects them into Neovim only. When running outside Neovim (e.g. Claude Code under Remote Control) and needing them, use the devshell: nix develop ~/.dotfiles#dev -c <cmd> (or enter with nix develop ~/.dotfiles#dev). Mostly defined in the global mise config (stow/shared/.config/mise/config.toml), whose shims come ahead of what stays in nix/shared/toolchain.nix (Elixir, Nix tooling, rustup), in both the devshell and Neovim. To pin or update one tool, mise use -g <tool>@<version>, then mise install.

Repository Architecture

Nix Architecture Patterns

• Mixed stability: servers use stable nixpkgs; desktops and laptops (NixOS and Darwin) use unstable. The Raspberry Pi server is anchored to the stable nixpkgs pinned by the nixos-raspberrypi input (its nixpkgs, home-manager-rpi and disko all follow that pin — do not make them follow another nixpkgs, or kernel binary cache hits are lost)
• Module scope: nix/README.md decides where a package or setting goes (kaizen, a shared scope, one host or one user). Read it before adding one
• Configuration helpers: Use lib.mkDarwin, lib.mkNixos and lib.mkRpiNixos functions from nix/lib/
• Host discovery: Configurations auto-match hostname from nix/hosts/$HOSTNAME/
• LLM agent CLIs: Packaged agents (claude-code, codex, gemini-cli, opencode, pi, ...) come from the llm-agents flake input (numtide/llm-agents.nix) and are declared via the llmAgents option in nix/shared/home/llm-agents.nix (mergeable across common → platform → host configs). Do not make this input follow another nixpkgs — it is built/cached against its own pin (cache.numtide.com)
• No curl|bash installers in activation: AI/agent CLIs must come from llm-agents (patched, cached), not native installers. Prebuilt glibc binaries cannot run on NixOS (stub-ld), and install-if-missing activation scripts make rebuilds depend on third-party servers.