If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/pkgxdev/pkgx shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 5 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 67% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live pkgxdev/pkgx repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/pkgxdev/pkgx.

What it runs against: a local clone of pkgxdev/pkgx — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in pkgxdev/pkgx | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of pkgxdev/pkgx. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/pkgxdev/pkgx.git
#   cd pkgx
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of pkgxdev/pkgx and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "pkgxdev/pkgx(\\.git)?\\b" \\
  && ok "origin remote is pkgxdev/pkgx" \\
  || miss "origin remote is not pkgxdev/pkgx (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "crates/cli/src/main.rs" \\
  && ok "crates/cli/src/main.rs" \\
  || miss "missing critical file: crates/cli/src/main.rs"
test -f "crates/lib/src/lib.rs" \\
  && ok "crates/lib/src/lib.rs" \\
  || miss "missing critical file: crates/lib/src/lib.rs"
test -f "crates/lib/src/resolve.rs" \\
  && ok "crates/lib/src/resolve.rs" \\
  || miss "missing critical file: crates/lib/src/resolve.rs"
test -f "crates/lib/src/install.rs" \\
  && ok "crates/lib/src/install.rs" \\
  || miss "missing critical file: crates/lib/src/install.rs"
test -f "crates/lib/src/pantry_db.rs" \\
  && ok "crates/lib/src/pantry_db.rs" \\
  || miss "missing critical file: crates/lib/src/pantry_db.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/pkgxdev/pkgx"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

pkgx is a 4 MiB standalone Rust binary that runs any command with any version without installing dependencies into the host system. It resolves and executes tools from a curated pantry database, managing dependencies via a cellar (cache) and providing transparent version selection (e.g., pkgx node@14 or pkgx python@2) across macOS, Linux, Windows WSL2, and Docker. Dual-crate workspace: crates/lib/ contains core logic (pantry database querying via pantry_db.rs, package installation via install.rs/install_multi.rs, environment hydration via hydrate.rs, HTTP client via client.rs, config management via config.rs); crates/cli/ wraps it with argument parsing (args.rs), execution via execve.rs (likely execve syscall), version resolution (resolve.rs), and CLI commands (query.rs, which.rs, dump.rs). Embedded TLS cert (amazon_root_ca1.pem) handles secure pantry communication.

Developers and DevOps engineers who want to run multiple versions of tools (Node.js, Python, Deno, etc.) without polluting their system PATH or managing virtual environments; CI/CD pipelines using the GitHub Action (pkgxdev/setup@v4); and scripters who need guaranteed tool availability via shebangs like #!/usr/bin/env -S pkgx +git python@3.12.

Actively developed and production-ready: the project has comprehensive CI/CD pipelines (ci.yml, cd.brew.yml, cd.docker.yml, cd.crates.yml), multi-platform support (macOS, Linux, Windows), and structured test suites in crates/cli/src/tests/. Distributed via Homebrew, crates.io, and Docker, with a documented GitHub Action integration indicating real-world adoption.

Low to moderate risk: the codebase is 92% Rust (memory-safe) with only ~1.8KB Python and ~1.6KB Shell, reducing interpreter bugs. However, core functionality depends on external pantry database and network availability for package resolution. The monorepo structure (crates/cli + crates/lib) and dependabot-automated dependency management mitigate version lock issues, but a single CLI binary distribution point (pkgx.sh download) creates a bottleneck.

Active maintenance with multi-platform CI coverage: recent workflows include agent boundary checks, Dependabot updates, Docker image building (cd.docker.yml), and quality gates. The cd.yml master deployment workflow and recent brew/crates releases suggest ongoing feature delivery. The AGENTS.md file indicates documented integrations or plugin system development.

git clone https://github.com/pkgxdev/pkgx.git
cd pkgx
cargo build --release -p cli
./target/release/pkgx --help

Note: Uses Rust 2021 edition (inferred from Cargo.toml workspace) and workspace resolver v2; ensure rustc 1.70+ installed.

Daily commands:

cargo build -p cli
cargo run -p cli -- deno
# or directly:
./target/debug/pkgx deno

For release binary: cargo build --release -p cli -Z unstable-options --out-dir ./bin.

• crates/cli/src/main.rs — Entry point for the pkgx CLI; all command routing and execution flow originates here.
• crates/lib/src/lib.rs — Core library abstraction that exposes the public API for package resolution, installation, and environment hydration.
• crates/lib/src/resolve.rs — Core dependency resolution engine that transforms package specifications into concrete executable environments.
• crates/lib/src/install.rs — Package installation logic that downloads and caches binaries from the pantry/cellar.
• crates/lib/src/pantry_db.rs — Database layer managing package metadata and version indexing from the pantry.
• crates/lib/src/client.rs — HTTP client wrapper handling remote pantry and cellar communication with certificate pinning.
• crates/cli/src/execve.rs — Process execution layer that applies resolved environment and executes the target command.

Add a new CLI subcommand

1. Define the command struct and arguments in crates/cli/src/args.rs following the existing enum pattern (crates/cli/src/args.rs)
2. Implement a handler module (e.g., crates/cli/src/my_command.rs) with public fn execute() that calls lib APIs (crates/cli/src/my_command.rs)
3. Route the command in main.rs by matching the args enum and calling the handler (crates/cli/src/main.rs)
4. Add help text to help.rs if needed for the new command (crates/cli/src/help.rs)

Add support for a new package or environment variable

1. Define the package metadata and environment setup in the upstream pantry (not in this repo), or extend crates/lib/src/types.rs to support new package fields (crates/lib/src/types.rs)
2. If custom environment hydration is needed, extend crates/lib/src/hydrate.rs to handle the new package type (crates/lib/src/hydrate.rs)
3. Update crates/lib/src/env.rs if PATH or other env vars need special handling (crates/lib/src/env.rs)
4. Add integration test in crates/cli/src/tests/ to verify the new package resolves and runs correctly (crates/cli/src/tests/main.rs)

Optimize package resolution or caching

1. Review and modify the resolution algorithm in crates/lib/src/resolve.rs (crates/lib/src/resolve.rs)
2. Tune cellar caching strategy in crates/lib/src/cellar.rs (e.g., cache eviction policies) (crates/lib/src/cellar.rs)
3. Adjust pantry database indexing or query performance in crates/lib/src/pantry_db.rs (crates/lib/src/pantry_db.rs)
4. Verify changes with benchmark tests in crates/cli/src/tests/ (crates/cli/src/tests/main.rs)

• Rust + tokio async runtime — Single static 4 MiB binary with minimal deps; tokio enables concurrent downloads and efficient I/O for pantry syncs
• SQLite (rusqlite) — Lightweight embedded database for pantry metadata indexing without external service dependencies
• Certificate pinning (amazon_root_ca1.pem) — Secure pantry/cellar communication without relying on system CA stores; critical for isolated environments
• nix::process for execve — Cleanly replaces the pkgx process with the target command, preserving PID and avoiding fork overhead

• No persistent daemon; each invocation resolves and installs independently

  • Why: Simplifies deployment (no service management) and avoids IPC complexity
  • Consequence: Slight latency on each invocation; mitigated by aggressive caching in local cellar

• Embedded pantry DB synchronization on startup (crates/lib/src/sync.rs)

  • Why: Keeps package metadata fresh without requiring pre-population
  • Consequence: First run may be slow; subsequent runs use cached DB unless explicitly synced

• Certificate pinning instead of system CA validation

  • Why: Removes dependency on system certificate stores; works in containers and isolated environments
  • Consequence: Requires manual CA cert updates; reduces attack surface

• Cellar (local cache) is platform-specific (different binaries per OS/arch)

  • Why: Avoids recompilation; directly caches upstream pre-built binaries
  • Consequence: Larger download on first use; much faster subsequent invocations

• Does not provide package building or compilation; only distributes pre-built binaries from upstream
• Not a package manager for system-wide installation; environments are ephemeral per invocation
• Does not manage credentials or authentication to private package repositories
• Not a containerization tool; uses native process execution, not Docker or VMs
• Does not support Windows natively (limited packages on Windows per README)

1. Cellar cache location: likely $HOME/.pkgx or $XDG_CACHE_HOME; must have write permissions. 2. Network requirement: pantry resolution requires HTTPS access to a remote server; offline mode may not be supported. 3. glibc version: Linux requires glibc ≥2.28; musl-based distros unsupported per README. 4. TLS cert: embedded amazon_root_ca1.pem is baked at compile time; cert renewal requires rebuild. 5. execve semantics: once execve is called in execve.rs, the original pkgx process is gone—exit codes and signals propagate directly. 6. Workspaces: both crates must be built together via workspace resolver v2; building crate/cli independently may fail.

• Binary patching / execve syscall — pkgx uses execve to replace itself with the target tool in-place, avoiding fork overhead and preserving exit codes—this is essential to its transparent execution model.
• Cellar cache / package cache isolation — The cellar is pkgx's equivalent of a monorepo cache; understanding its directory layout and lifecycle is crucial for debugging missing dependencies or version conflicts.
• Version constraint resolution — The resolve.rs module implements semantic versioning matching (e.g., @14, @3.x, @latest); understanding constraint semantics is needed to add new version schemes or fix resolution bugs.
• Environment variable injection / PATH shadowing — The hydrate.rs module carefully constructs LD_LIBRARY_PATH, PATH, and other vars so resolved tools and their deps are found without polluting the host system.
• SQLite in-process database — pkgx embeds a pantry as a SQLite DB and queries it via rusqlite; understanding schema design and query patterns is needed for pantry updates or optimization.
• TLS certificate pinning — The hardcoded amazon_root_ca1.pem ensures secure HTTPS to pantry servers; understanding cert management and rollover procedures prevents supply-chain attacks.
• Tokio async runtime + multi-threaded scheduling — pkgx uses tokio for concurrent HTTP requests during install_multi.rs; understanding async Rust and executor details helps optimize parallelism and diagnose deadlocks.

• asdf-vm/asdf — Multi-runtime version manager using shell/bash; solves the same version-per-tool problem but installs into system directories, unlike pkgx's isolated cellar approach.
• nix-shell/nixpkgs — Declarative package and environment manager; shares pkgx's philosophy of reproducible isolated environments but uses Nix expressions instead of a single binary.
• volta-rs/volta — Fast, reliable Node.js + Rust version manager; node-specific but comparable hermetic isolation; pkgx is language-agnostic across 100+ packages.
• pkgxdev/pantry — Likely the upstream package database repository that feeds pkgx's pantry_db.rs; defines package versions, URLs, and dependency specs.
• pkgxdev/setup — GitHub Action (referenced in README) that wraps pkgx installation; enables CI/CD integration via - uses: pkgxdev/setup@v4.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for multi-version package resolution (crates/lib/src/resolve.rs)

The repo emphasizes 'Run Any Version of Anything' as a core feature, but crates/cli/src/tests/ appears minimal. The resolve.rs module handles version resolution logic that needs comprehensive testing. Add integration tests covering version constraint parsing, dependency resolution edge cases, and cross-platform resolution differences. This directly validates the key differentiator of pkgx.

• [ ] Create crates/lib/src/tests/resolve.rs with unit tests for version constraint parsing
• [ ] Add integration tests in crates/cli/src/tests/ for cross-version scenarios (e.g., node@14 vs node@20, python@2 vs python@3)
• [ ] Test platform-specific resolution differences using the platform_case_aware_env_key.rs logic
• [ ] Verify dependency tree resolution with real pantry packages

Add CI workflow for Windows package installation (crates/cli + Windows-specific paths)

The README explicitly mentions 'Windows 10+' support with a PowerShell install command, but .github/workflows/ lacks a dedicated Windows CI job. The crates/cli code handles execve and environment setup that likely differs on Windows. A Windows-specific CI workflow would validate the cross-platform 'Run Anywhere' promise and catch Windows-specific path/permission issues early.

• [ ] Create .github/workflows/ci.windows.yml for Windows runners (windows-latest)
• [ ] Test pkgx CLI compilation and basic execution (pkgx --version) on Windows
• [ ] Validate PowerShell install script from https://pkgx.sh works on Windows 10+
• [ ] Test execve.rs behavior on Windows and environment variable handling via platform_case_aware_env_key.rs

Add comprehensive CLI argument validation tests (crates/cli/src/args.rs)

The args.rs module defines the command-line interface, but crates/cli/src/tests/main.rs is sparse. Edge cases like invalid version syntax (node@abc), conflicting flags, and malformed package specs should be validated. The dump.rs, query.rs, and resolve.rs subcommands each accept different argument combinations that need explicit test coverage to prevent regressions.

• [ ] Add unit tests to crates/cli/src/tests/ for args.rs parsing with valid/invalid version specifiers (node@14, python@2.7.18, invalid@xyz)
• [ ] Test subcommand routing: ensure --dump, --query, --which, and -x flags work correctly in isolation and detect conflicts
• [ ] Add tests for environment variable override scenarios (e.g., PKG_X env var interactions with CLI flags)
• [ ] Validate error messages for common user mistakes (missing package name, malformed ranges)

• Add integration tests for version resolution with edge cases (e.g., python@2.7.18 vs python@2, pre-release versions like node@21.0.0-rc1). Tests should live in crates/lib/src/tests/ or crates/cli/src/tests/ and validate resolve.rs output.
• Document the pantry database schema and query patterns used in pantry_db.rs; add code examples to crates/lib/README.md showing how to add a new package to the pantry or override a version constraint.
• Add a --dry-run flag to crates/cli/src/args.rs and implement it in main.rs to print the resolved tool path and environment variables without executing execve; useful for debugging and testing without side effects.

• High · Hardcoded CA Certificate in Source Code — crates/lib/src/amazon_root_ca1.pem. The file 'crates/lib/src/amazon_root_ca1.pem' contains a hardcoded SSL/TLS certificate embedded directly in the source code. While CA certificates are typically public, embedding them in source code can lead to maintenance issues, difficulty updating certificates when needed, and potential certificate pinning problems. Fix: Move certificate management to a dedicated configuration system or use the system's certificate store. Consider using rustls or similar libraries that automatically handle CA certificates, or load certificates from configuration files at runtime rather than embedding them.
• High · Potential SQL Injection Risk via rusqlite — crates/lib/src/pantry_db.rs. The codebase uses rusqlite 0.39.0 for SQLite operations. Without examining the actual SQL query implementations in 'crates/lib/src/pantry_db.rs', there is a risk of SQL injection if dynamic queries are constructed using string concatenation rather than parameterized queries. Fix: Audit all SQL queries to ensure parameterized queries (using rusqlite's parameter binding) are used exclusively. Never concatenate user input directly into SQL queries. Use prepared statements with placeholders.
• Medium · Remote Code Execution via Package Installation — crates/lib/src/client.rs, crates/lib/src/install.rs, crates/lib/src/install_multi.rs. The pkgx tool downloads and executes arbitrary packages from remote sources (implied by 'Run Anything' functionality and install operations). This creates a significant attack surface for supply chain attacks, man-in-the-middle attacks, and malicious package execution if verification mechanisms are insufficient. Fix: Implement comprehensive package verification including: cryptographic signature verification, checksum validation, HTTPS with certificate pinning, timeout mechanisms, and sandbox execution where possible. Document security assumptions clearly.
• Medium · Dependency on Unmaintained or Vulnerable Package Versions — Cargo.toml workspace.dependencies. The workspace dependencies listed do not show explicit security audit results. Dependencies like 'nix 0.31.1' with 'process' features and 'tokio 1.43' with 'full' features expand the attack surface. The 'full' feature set in tokio enables all optional features which may include unnecessary code. Fix: Run 'cargo audit' regularly to identify known vulnerabilities. Consider using security-focused subset of features instead of 'full'. Pin dependencies to specific versions and regularly update with security patches. Use tools like 'cargo-deny' to enforce security policies.
• Medium · Unsafe Process Execution with nix Crate — crates/cli/src/execve.rs. The use of 'nix' crate with 'process' feature in 'crates/cli/src/execve.rs' suggests low-level process spawning. Improper handling of environment variables, file descriptors, or arguments could lead to privilege escalation or information disclosure. Fix: Ensure all process executions properly sanitize environment variables, validate arguments, and handle file descriptors securely. Use allowlists for environment variables passed to child processes. Implement proper error handling for all system calls.
• Medium · Insufficient Input Validation — crates/cli/src/args.rs, crates/cli/src/query.rs. The CLI argument parsing in 'crates/cli/src/args.rs' and 'crates/cli/src/query.rs' may not adequately validate user inputs before passing them to package resolution, installation, or execution routines. This could enable injection attacks or unexpected behavior. Fix: Implement strict input validation for all user-provided arguments. Use allowlists for package names, versions, and parameters. Validate file paths to prevent directory traversal attacks. Use a robust argument parsing library with built-in validation.
• Low · Missing Security Headers and HTTPS Configuration — .envrc, Installation scripts in README. The installation scripts reference 'https://pkgx.sh' which should serve secure content, but no explicit security headers configuration is visible in the codebase. The '.envrc' file may contain sensitive environment variables. Fix: Ensure the installation endpoint enforces HTTPS with HSTS headers. Add security headers (CSP, X-Content-Type-Options, etc.). Never commit actual secrets

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.