llm-agents.nix AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• Root: flake.nix, flake.lock, devshell.nix, README.md.
• Packages live under packages/<tool>/ with package.nix, optional update.py, and lockfiles when needed.
• Formatting config: packages/formatter/treefmt.nix.
• Utilities and docs: scripts/, docs/, .github/.

Build, Test, and Development Commands

• Enter dev shell: nix develop.
• Build a package: nix build --accept-flake-config .#<package> (e.g., nix build .#claude-code).
• Run without installing: nix run .#<package> -- --help.
• Repo checks (builds + lints): nix flake check.
• Format everything: nix fmt.
• Regenerate README package section: ./scripts/generate-package-docs.nu.

Coding Style & Naming Conventions

• Indentation: 2 spaces; avoid tabs.
• Nix: small, composable derivations; prefer buildNpmPackage/rustPlatform.buildRustPackage/stdenv.mkDerivation as in existing packages.
• File layout per package: package.nix (definition), update.py (optional custom updater), nix-update-args (optional nix-update flags). package.nix is called from a scope that contains all in-repo packages and helpers (buildNpmPackage, wrapBuddy, formatelf, versionCheckHomeHook, bun2nixLib, platformSource, flake, ...), so declaring one of these names as a function argument is enough.
• Tools via treefmt: nixfmt, deadnix, shfmt, shellcheck, mdformat, yamlfmt, taplo. Always run nix fmt before committing.

Updating Packages

Prefer nix-update over custom update scripts. Most packages can be updated with:

nix run nixpkgs#nix-update -- --flake <package>

For this to work, package.nix must have version/hash attributes inline (not loaded from JSON):

buildGoModule rec {
  pname = "example";
  version = "1.0.0";  # nix-update finds and updates this

  src = fetchFromGitHub {
    owner = "owner";
    repo = "repo";
    rev = "v${version}";
    hash = "sha256-...";  # nix-update updates this
  };

  subPackages = [ "." ];  # for go find the relevant packages containing the binary

  vendorHash = "sha256-...";  # nix-update updates this too
}