nxv
AGENTS.md136 starsChanged 3 months agoMITView on GitHub
CLAUDE.md is a symlink to this file — edit here. nxv (Nix Versions) is a Rust CLI tool for quickly finding specific versions of Nix packages across nixpkgs history. It uses a pre-built SQLite index with bloom filters for fast lookups. Also provides an HTTP API server with web frontend. This project uses Nix flakes with crane for reproducible builds: The devshell provides shortcuts for all of these (build, clippy, fmt-check, run-tests, coverage, ...). ci-local runs the exact CI sequence:…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,439 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository6 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- nxv-designSkill
- nxvSkill
- source-command-releaseSkill
- nxv-designSkill
- nxvSkill
The file
We split this AGENTS.md into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 100
Observations, not inference: every stored commit is one at which the version verifiably existed.
- Distinctive: line 108
Always use current versions: Before adding dependencies:
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
This file provides guidance to AI coding agents (Claude Code, Codex, etc.) when working with code in this repository. CLAUDE.md is a symlink to this file — edit here.
Project Overview
nxv (Nix Versions) is a Rust CLI tool for quickly finding specific versions of Nix packages across nixpkgs history. It uses a pre-built SQLite index with bloom filters for fast lookups. Also provides an HTTP API server with web frontend.
Development Environment
This project uses Nix flakes with crane for reproducible builds:
nix develop # Enter devshell with Rust toolchain
direnv allow # Or use direnv for automatic shell activationBuild Commands
cargo build # Debug build
cargo build --release # Release build
cargo build --features indexer # Build with indexer feature
cargo run -- <args> # Run with arguments
cargo test # Run default test suite (unit + integration)
cargo test --features indexer # Include indexer tests (some #[ignore]d ones need `nix` + network)
cargo test <test_name> # Run a single test by name
cargo test db:: # Run tests in a specific module
cargo clippy --features indexer -- -D warnings # Lint (matches CI; CI also runs the featureless variant)
cargo fmt # Format code
cargo bench # Run benchmarks (bloom, search, indexer)
nix flake check # Run all Nix checks (build, clippy, fmt, tests, a11y)The devshell provides shortcuts for all of these (build, clippy, fmt-check, run-tests, coverage, ...). ci-local runs the exact CI sequence: fmt-check, clippy, test — all with --features indexer.
Nix Flake Outputs
nix build # Build nxv (user binary)
nix build .#nxv-indexer # Build with indexer feature
nix build .#nxv-static # Static musl build (Linux only; native arch)
nix build .#nxv-static-aarch64 # Static musl build (aarch64, cross-compiled on x86_64 Linux)
nix build .#nxv-docker # Docker image (Linux only, use --system x86_64-linux on macOS)
nix run # Run nxv directly
nix run .#nxv-indexer # Run with indexer featureArchitecture
Data Flow
- Index Download (
remote/): User runsnxv sync→ downloads compressed SQLite DB + bloom filter from remote manifest - Search (
db/queries.rs): Queries go through bloom filter first (fast negative lookup), then SQLite with FTS5 - Output (
output/): Results formatted as table (default), JSON, or plain text
Backend Abstraction (backend.rs, client.rs)
The CLI transparently runs against either a local index or a remote nxv serve instance. main.rs branches on NXV_API_URL — if set, ApiClient (HTTP) is used; otherwise the local SQLite/bloom backend is used. Both are handled through a single Backend enum (Local(Database) | Remote(ApiClient)) with matching methods, so command handlers are backend-agnostic. search.rs holds the search logic shared by the CLI commands and the API server handlers.
Self-Update (self_update.rs)
nxv update only checks for and installs the latest nxv application release. On local installs (install.sh, manual download) the binary is replaced atomically after SHA-256 verification against the release's SHA256SUMS.txt; on managed installs (Nix, cargo, Homebrew — detected from the executable path) it only prints the matching upgrade command. nxv sync independently downloads or refreshes the package index and never updates the application. An incompatible index tells users to update the application and retry the sync. Note: NXV_VERSION is read only by install.sh to pin the installer download — the binary's application update always targets the latest release.
API Server (server/)
The nxv serve command runs an HTTP API server with:
- REST API at
/api/v1/*(search, package info, version history, stats) - Web frontend at
/served fromfrontend/(static HTML/CSS/JS, embedded at build time) - OpenAPI documentation at
/docs(generated inserver/openapi.rs) - Configurable CORS support
- In-memory runtime metrics (
server/metrics.rs): rolling latency window, per-minute activity buckets over the last 30 minutes, uptime — all lost on restart by design
Shell Completions (completions.rs)
nxv completions <shell> emits clap-generated completions; for bash/zsh/fish it appends custom functions that call the hidden nxv complete-package subcommand for dynamic package-name completion against the local index.
Indexer (src/index/, feature-gated)
Note the directory is src/index/ even though the Cargo feature is named indexer. The indexer ingests channel-release snapshots from releases.nixos.org — it does NOT walk git history or read a nixpkgs checkout (see docs/indexer-rewrite/DESIGN.md for the full specification and ANALYSIS.md for why the git-walking design was replaced):
releases.rs: S3 bucket listing (event-based XML parsing), release-name parsing, git-revision fetch, planning (diff against thereleasesledger)snapshot.rs: Streaming brotli + JSON parsing ofpackages.json.br(~380 MB decompressed, never materialized; era-tolerant field handling back to 2020)eval.rs:nix-envovernixexprs.tar.xzfor the pre-2020 era (--backfill-evals), and the--head-evalmaster-tarball fallback for channel-stuck periods (the only paths that neednix)monitor.rs: Data-quality gates that run BEFORE any write — count floors, rolling baselines, sentinel packages (firefox, thunderbird, nh, python*Packages.requests), births/deaths, head-lag; plus the end-of-run report (--report report.json)mod.rs: Coordinator — plan → parallel fetch/parse → in-order gating → aggregated widen-only upserts (atomic with the ledger) → FTS/bloom rebuild + watermarkspublisher.rs: Generates compressed index files and manifest for distribution (min_version defaults to the schema version; refuses to publish v4 ungated)
Database Schema (db/mod.rs, schema v4)
package_versions: One row per(attribute_path, version)with observation-backed bounds: the pair was seen atfirst_commitandlast_commit(real, Hydra-built channel commits); interior presence is interpolated, not guaranteedidx_packages_search_nocase: Covering ASCII-NOCASE index for prefix and prefix+version candidate ranking; bulk ingestion drops and transactionally rebuilds it, and publication repairs or refuses an incomplete indexreleases: Per-channel ingestion ledger (pending/ingested/failed/skipped + retry backoff) — replaces the old single-checkpoint model; a gap is just a pending row the next run picks uppackage_versions_fts: FTS5 virtual table for description search (triggers are WHEN-guarded; bulk runs drop + rebuild)meta: Key-value store (last_indexed_commit = newest ingested release commit, schema_version, min_schema_version)
Key Design Decisions
- Observations, not inference: every stored commit is one at which the version verifiably existed; no file→attr change mapping, no "no evaluation = unchanged" (the root causes of issues #21/#23)
- Nested package sets included: packages.json already enumerates all ~144k attrs (python3xxPackages., haskellPackages., ...) — issue #5 is covered with zero evaluation cost
- Currency: nixos-unstable-small ingestion keeps the index hours behind master;
--head-evalcovers channel stalls; head lag over 72h marks the run unhealthy (a fatal error under--strict; the publish workflow instead publishes first and alerts after) - Bloom filter: Serialized to separate file, loaded at search time for instant "not found" responses; contains full dotted attribute paths
- Feature gates: Indexer code (ctrlc, brotli, quick-xml) only compiled with
--features indexerto keep user binary small
Dependency Management
Always use current versions. Before adding dependencies:
cargo search <crate> # Find latest versionEnvironment Variables
Most are also exposed as CLI flags (see src/cli.rs); env vars are useful for tests and deployment.
NXV_API_URL— point the CLI at a remotenxv serveinstead of the local DBNXV_API_TIMEOUT— HTTP client timeout in seconds (default 30)NXV_DB_PATH— override local SQLite pathNXV_MANIFEST_URL— override the manifest URL fornxv syncNXV_SKIP_VERIFY— skip minisign verification of the manifestNXV_PUBLIC_KEY— override the embedded minisign public keyNXV_VERSION— pin the versioninstall.shdownloads (not read by the binary itself)NXV_HOST,NXV_PORT,NXV_RATE_LIMIT,NXV_RATE_LIMIT_BURST—nxv servebind/host/rate-limitNXV_MAX_DB_CONNECTIONS,NXV_DB_TIMEOUT_SECS—nxv serveDB concurrency cap (default 32) and per-operation timeout (default 30s)NXV_LOG_FORMAT— set tojsonfor structurednxv servelogs (combine withRUST_LOG)NXV_SECRET_KEY— minisign secret key (path or contents) fornxv publishsigningNXV_RELEASES_URL— override the releases.nixos.org S3 endpoint fornxv index(tests, mirrors)NXV_GITHUB_API_BASE— override the GitHub API base URL used bynxv update's self-update check (tests, mirrors)NXV_FRONTEND_DIR— serveindex.html/app.js/favicon.svgfrom this directory on every request instead of the embedded copy, and disable the 24hCache-Controlfor those routes. Used by the devshelldevcommand for live frontend reload (edit → browser refresh, no rebuild;devalso runs cargo-watch sosrc/changes rebuild and restart the server). Unset in production.NXV_GIT_REV— set by the Nix flake build to embed the git rev in--version
Data Paths
The database and bloom filter are stored in platform-specific data directories:
- macOS:
~/Library/Application Support/nxv/ - Linux:
~/.local/share/nxv/
Files:
index.db- SQLite database with package versionsindex.bloom- Bloom filter for fast negative lookups (derived from the db filename; the distributed release artifact is separately namedbloom.bin)
Testing
- Unit tests are in each module's
mod testssection - Integration tests in
tests/integration.rsuseassert_cmdto test CLI behavior - Tests create temporary databases using
tempfile - Some indexer tests require
nixto be installed (marked#[ignore])
Accessibility (WCAG)
Frontend a11y is audited by two devshell commands:
a11y— static, fully offline. Runshtml5validatoragainstfrontend/*.html(CSS validation is skipped — vnu.jar predates Tailwind v4 oklch/@theme/@layer/color-mix) and thenscripts/a11y_check.py frontend/index.html. The Python script enforces landmarks, form labels, alt/role on images and SVGs, heading hierarchy, skip-link presence, dialog semantics, and converts every oklch token in the@themeblock to sRGB to flag fg/bg pairs below WCAG 2.1 AA (4.5:1 text, 3:1 large/UI). Wired intonix flake checkasnxv-a11y.a11y-live— dynamic, opt-in. Runspa11y-civianpxagainst the localnxv serve(start it first withdev). Config atfrontend/.pa11yci.jsoncovers the home page (desktop + mobile), a search-populated state, and the command palette open state. Not wired intonix flake check— needs a running server and pulls from npm on first run.
Docs Site (VitePress)
The VitePress site under website/ is managed by four devshell commands
(they cd website and delegate to bun, which is provided in the shell):
docs-dev— start the local dev server (bun run dev). Default port is 5173; the site is served under/nxv/to match the GitHub Pages base.docs-build— build the static site intowebsite/.vitepress/dist.docs-preview— serve the already-built site for a final look.docs-fmt— run Prettier overwebsite/.
NixOS Module
A NixOS module is provided for running nxv as a systemd service:
{
imports = [ inputs.nxv.nixosModules.default ];
services.nxv = {
enable = true;
port = 8080;
# dataDir = "/var/lib/nxv"; # Optional custom data directory (holds index.db + bloom filter)
};
}Agent Skill
The canonical skill template lives at src/skill/SKILL.md — it is embedded
in the binary and installed by nxv skill install for every major AI coding
agent (Claude Code, Codex, Pi, OpenClaw, Copilot, Cursor, Gemini, Amp,
Goose; see src/skill/mod.rs for the path table). The checked-in copies at
.claude/skills/nxv/SKILL.md and .agents/skills/nxv/SKILL.md are
generated — never edit them directly. After editing the template,
regenerate both with cargo run -- skill install claude agents --dir .
(the test_checked_in_skill_copies_match_template integration test enforces
this). When changing CLI flags, adding/removing subcommands, or altering
JSON / API response shapes, also update the template so the skill stays
accurate. The user-facing guide lives at website/guide/skill.md.
Design System Skill (nxv-design)
The "Blueprint" design system — the UI design spec for the web frontend
(frontend/) and the docs site (website/) — is installed as a project
skill at .claude/skills/nxv-design/ (Claude Code) and
.agents/skills/nxv-design/ (Codex). The two copies are identical mirrors;
update both together. It is managed in Claude designs and re-exported as a
zip — when a new export lands, replace both directories wholesale rather
than hand-editing. Consult this skill (tokens, README.md, ui_kits/)
before any visual change to the web frontend or docs site; all colour,
type, spacing, and voice decisions must trace back to its tokens and
guidelines. The look is dark-only — never add a light mode.
Releasing
Releases are automated with release-plz (release-plz.toml +
.github/workflows/release-plz.yml). On every push to main it maintains a
chore: release vX.Y.Z PR (version bump + CHANGELOG from conventional
commits; feat: bumps the 0.x minor via features_always_increment_minor).
Merging that PR ships the release: release-plz pushes the vX.Y.Z tag,
which triggers release.yml and flakehub-publish-tagged.yml. Both
release-plz jobs author with a GitHub App token (secrets
RELEASE_PLZ_APP_ID / RELEASE_PLZ_APP_PRIVATE_KEY) — the default
GITHUB_TOKEN would neither trigger CI on the release PR nor fire the
tag-push workflows. Use /release to review and merge the release PR with
confirmation; never merge it without explicit user approval.
CI/CD & Index Publishing
GitHub Actions Workflows
ci.yml: Runs on PRs and main - tests (cargo + nix), clippy, fmt, builds Docker latest on mainrelease-plz.yml: On pushes to main - maintains the release PR; tagsvX.Y.Zwhen it merges (see Releasing)release.yml: Triggered byv*tags - builds static binaries, publishes to crates.io, pushes versioned Docker imagespublish-index.yml: Every 6 hours or manual - ingests new channel-release snapshots into the index (--head-eval --report, deliberately not--strict) and republishes toindex-latestonly when something was ingested (orforce_publish); monitor anomalies turn the run red AFTER publishing instead of blocking itpages.yml: Deploys the VitePress docs site (website/) to GitHub Pages on pushes to mainflakehub-publish-tagged.yml: Publishes tagged releases to FlakeHub
Publishing the Index
The default manifest URL is https://github.com/utensils/nxv/releases/download/index-latest/manifest.json.
To publish manually with signing:
nxv publish --url-prefix "https://github.com/utensils/nxv/releases/download/index-latest" --secret-key keys/nxv.keyOr trigger the workflow:
gh workflow run publish-index.ymlRequired Secrets
CACHIX_AUTH_TOKEN: Nix binary cacheCARGO_REGISTRY_TOKEN: crates.io publishingNXV_SIGNING_KEY: Manifest signing (minisign secret key)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

