pkgrep

pkgrep helps developers and coding agents fetch dependency source code into a local cache and expose it in a project via symlinks for easy source traversal.

Disclosure

This project is currently written 100% by Codex (an AI coding agent), without human-written code contributions.

Do not use this project if you are not comfortable adopting and running code that is fully agent-written.

Why This Exists

Modern dependency managers often install packaged artifacts (compiled bundles, generated files, wheels, etc.), not easy-to-traverse source trees for a specific dependency version.

That creates a gap for agent-assisted development:

• Coding agents can infer intent faster when they can inspect real upstream implementation code.
• Developers need deterministic, reusable local source snapshots across projects.
• Teams need a simple workflow to link dependency source into a project without manual cloning and ad-hoc scripts.

pkgrep addresses this by caching dependency source centrally by version/fingerprint, linking it into each project in a consistent location, and tracking references so stale cache entries can be pruned safely.

Key Features

• 📦 Centrally managed dependency source cache with symlinked project links for efficient storage reuse
• 🤖 Non-interactive CLI by default for agent-friendly automation

Installation

Homebrew

brew tap thomasjiangcy/homebrew-tap
brew install pkgrep

GitHub Releases

Download the archive for your platform from the project Releases page and place pkgrep on your PATH.

Direct Download (curl / wget)

One-line install with curl:

curl -fsSL https://raw.githubusercontent.com/thomasjiangcy/pkgrep/main/install.sh | sh

One-line install with wget:

wget -qO- https://raw.githubusercontent.com/thomasjiangcy/pkgrep/main/install.sh | sh

Install a specific version:

curl -fsSL https://raw.githubusercontent.com/thomasjiangcy/pkgrep/main/install.sh | \
  sh -s -- --version v0.1.0

Install options:

./install.sh --help

Notes:

• install.sh auto-detects platform target and installs to ${HOME}/.local/bin by default.
• It resolves --version latest via GitHub Releases API.
• It verifies archive checksum when .sha256 is available.
• Override release source for forks with --repo <owner/repo>.

From source

git clone https://github.com/thomasjiangcy/pkgrep.git
cd pkgrep
cargo install --path .

Verify

pkgrep --help

Agent Skill

This repo includes an Agent Skills-compatible usage skill at skills/pkgrep-usage.

Install via the pkgrep CLI into the current project (default target: <cwd>/.agents/skills):

pkgrep skill install

Install globally (default target: $HOME/.agents/skills):

pkgrep skill install --mode global

Install into a custom skills directory:

pkgrep skill install --target /path/to/skills

Replace an existing install with the latest bundled copy:

pkgrep skill install --force

Initialize project-local pkgrep integration:

pkgrep init

Usage

pkgrep currently exposes these commands:

• pkgrep pull [dep-spec ...]
• pkgrep pull --fallback-repo-head [dep-spec ...]
• pkgrep list [--json]
• pkgrep init
• pkgrep path <dep-spec>
• pkgrep remove <dep-spec ...> [--yes]
• pkgrep skill install [--mode project|global] [--target <skills-dir>] [--force]
• pkgrep self update
• pkgrep cache clean [--yes]
• pkgrep cache prune [--yes]

Examples:

# Pull git dependency source at the remote default branch tip
pkgrep pull git:https://github.com/facebook/react.git

# Pull explicit git dependency source
pkgrep pull git:https://github.com/facebook/[email protected]

# Pull npm package source by package version
pkgrep pull npm:[email protected]

# If exact source mapping fails, explicitly fall back to the repo default branch
pkgrep pull --fallback-repo-head npm:@types/[email protected]

# Pull crates.io package source by package version
pkgrep pull crates:[email protected]

# Pull package source using implicit ecosystem inference from project lockfile(s)
# (works only when exactly one supported ecosystem is detected in cwd)
pkgrep pull [email protected]

# Pull npm package source using registry latest tag
pkgrep pull npm:react

# Pull npm package source using the installed project version when available
pkgrep pull react

# Pull PyPI package source by package version
pkgrep pull pypi:[email protected]

# Pull PyPI package source using registry latest version
pkgrep pull pypi:fastapi

# Pull explicit git dependency source when tag/revision contains '@'
pkgrep pull 'git:https://github.com/facebook/react.git@[email protected]'
# equivalent unambiguous form:
pkgrep pull 'git:https://github.com/facebook/react.git#[email protected]'

# Pull from project files in current directory
# (currently auto-detects package-lock.json, pnpm-lock.yaml, yarn.lock, uv.lock, and Cargo.lock, and only pulls entries with git source hints)
pkgrep pull

# Initialize project-local pkgrep files
pkgrep init

# Resolve the linked project path for a dep
pkgrep path git:https://github.com/facebook/[email protected]
pkgrep path npm:[email protected]
pkgrep path pypi:[email protected]

# List linked deps in the current project
pkgrep list
pkgrep list --json

# Remove project links (requires --yes)
pkgrep remove git:https://github.com/facebook/[email protected] --yes

# Clean local cache (requires --yes)
pkgrep cache clean --yes

# Prune unreferenced cached checkouts/mirrors (dry-run by default)
pkgrep cache prune
pkgrep cache prune --yes

# Update pkgrep from GitHub Releases (for direct installs)
pkgrep self update

Current behavior:

• remove, cache clean, and cache prune are no-op unless --yes is provided.
• pull supports:
  • explicit git specs without a revision (git:<url>), resolved to the remote default-branch commit at pull time
  • explicit git specs (git:<url>@<revision> or git:<url>#<revision>)
  • npm package specs (npm:<name> / npm:<name>@<version>) resolved via npm metadata
  • pull --fallback-repo-head ... as an explicit escape hatch when a package resolves to a repository URL but pkgrep cannot determine an exact upstream git revision
  • versionless npm package pulls prefer a project-local version detected from node_modules, package-lock.json, pnpm-lock.yaml, yarn.lock, or concrete package.json declarations before falling back to the registry latest tag
  • pypi package specs (pypi:<name> / pypi:<name>@<version>) resolved via PyPI metadata
  • versionless pypi package pulls prefer a project-local version detected from uv.lock before falling back to the registry latest tag
  • crates package specs (crates:<name> / crates:<name>@<version>) resolved via crates.io metadata
  • versionless crates package pulls prefer a project-local version detected from Cargo.lock before falling back to the registry latest tag
  • shorthand package specs (<name> / <name>@<version>) when exactly one supported ecosystem is inferred from project lockfiles in cwd
• path supports:
  • git-backed specs without a revision (git:<url>) when exactly one linked match exists
  • git-backed specs (git:<url>@<revision> / git:<url>#<revision>)
  • npm/pypi/crates package specs when matching links exist in project manifest metadata
  • versionless npm/pypi/crates specs (npm:<name>, pypi:<name>, crates:<name>) only when exactly one linked match exists
  • for legacy manifest entries without package-version metadata, versioned npm/pypi/crates lookups may require re-running pkgrep pull <spec> to backfill metadata
• Git dep specs accept git:<url>, git:<url>@<revision>, and git:<url>#<revision>.
• Project links are human-readable under .pkgrep/deps/...; internal cache keys remain normalized for safety/determinism.
• cache prune reconciles stale project references from the global index, then prunes unreferenced local checkouts and git mirrors.
• cache prune dry-run output shows human-readable dependency identities plus filesystem paths.
• self update is disabled for Homebrew-managed installs; use brew upgrade pkgrep in that case.

Local Index Files

pkgrep maintains two local JSON index files:

• Project manifest: .pkgrep/manifest.json
• Global reverse index: <cache_dir>/index/project_refs.json (default: ~/.pkgrep/index/project_refs.json)

Project manifest entry example:

{
  "schema_version": 1,
  "entries": {
    "git:https://github.com/facebook/react.git@[email protected]": {
      "link_path": ".pkgrep/deps/git/github.com/facebook/react.git@[email protected]",
      "cache_key": "git/b64_.../[email protected]/f1338f..."
    }
  }
}

Global reverse index entry example:

{
  "schema_version": 1,
  "entries": {
    "git/b64_.../[email protected]/f1338f...": {
      "dep_spec": "git:https://github.com/facebook/react.git@[email protected]",
      "checkout_path": "/home/user/.pkgrep/sources/git/b64_.../[email protected]/f1338f...",
      "projects": [
        "/home/user/projects/my-app"
      ]
    }
  }
}

Configuration

Config precedence:

1. Environment variables
2. Project config: <project>/pkgrep.toml
3. Global config: ${XDG_CONFIG_HOME:-~/.config}/pkgrep/config.toml
4. Defaults

Example pkgrep.toml:

cache_dir = "/tmp/pkgrep-cache"
worker_pool_size = 8

Worker pool default:

• max(4, min(16, 2 * available_parallelism))
• default cache dir: ~/.pkgrep (override with PKGREP_CACHE_DIR or config cache_dir)

Logging:

• default: warn with concise, human-readable formatting (no timestamp noise)
• CLI override: --verbose (uses debug)
• env override: RUST_LOG=debug

Registry metadata endpoint overrides (for private mirrors/airgapped environments):

• PKGREP_NPM_REGISTRY_URL (default: https://registry.npmjs.org)
• PKGREP_PYPI_REGISTRY_URL (default: https://pypi.org/pypi)

Contributing

See CONTRIBUTING.md for the full contributor guide.

Prerequisites:

• Rust toolchain from rust-toolchain.toml
• mise (required for project tooling)
• just (required task runner)
• lefthook (required for git hook checks)

Tooling via mise

mise install
just hooks-install

Common development commands:

just fmt
just lint
just test
just ci
just hooks-run

Git hooks:

• pre-commit: no-mocks policy + cargo fmt --check
• pre-push: clippy (-D warnings) + full test suite

Maintainer Release Flow

1. Create and push a version tag:

git tag v0.1.0
git push origin v0.1.0

2. GitHub Actions workflow Release builds and uploads platform artifacts to the GitHub Release.
3. The same Release workflow updates Formula/pkgrep.rb in your tap repository.

Required repo settings for Homebrew publish:

• Repository variable: HOMEBREW_TAP_REPOSITORY (example: owner/homebrew-tap)
• Repository secret: HOMEBREW_TAP_GITHUB_TOKEN (token with push access to the tap repo)

License

MIT