🚚 packref

Local, versioned package references for your coding agents.

Packref gives coding agents local copies of the exact dependency source used by a project. Agents can inspect implementation details without guessing from documentation, cloning an unrelated revision, or reading a different installed version.

Packref installs source for inspection only. It does not install runtime dependencies, modify your dependency manifest, or replace your package manager.

---

Features

• 🎯 Exact source alignment: Reference the package versions that the project actually uses.
• 🔎 Repository-first inspection: Prefer tagged repository source and retain monorepo layout when package metadata identifies a subdirectory.
• 📦 Reliable fallback: Use the published npm tarball when repository source is not available.
• 🔒 Reproducible references: Commit one Packref lockfile so every contributor can materialize the same package source references.
• ♻️ Shared source snapshots: Reuse immutable package source across projects through a deduplicated global store.
• 🤖 Agent-ready guidance: Add clear instructions that tell coding agents where and when to read dependency source.
• 🧭 Safe reconciliation: Sync dependency-tracked references without changing manual references or adopting unrelated dependencies.
• 🧰 Package-manager neutral: Work alongside Bun, npm, pnpm, and Yarn without replacing runtime dependency installation.

Quick start

Initialize Packref from the root of a project:

npx packref init

Initialization creates .packref/packref-lock.json, registers the project for global-store pruning, and can update .gitignore, tsconfig.json, and AGENTS.md with Packref guidance.

Non-interactive setup for agents

Use --non-interactive to initialize Packref entirely from flags. Add --ignore to update .gitignore and exclude .packref from TypeScript. Add --agents to write Packref guidance to AGENTS.md.

# Initialize only the Packref lockfile and project registration
npx packref init --non-interactive

# Recommended unattended setup for coding agents
npx packref init --non-interactive --ignore --agents

Omitted setup flags are disabled. The --ignore and --agents flags require --non-interactive; without setup flags, packref init keeps the interactive setup flow.

Add the exact installed version of a dependency, request a package and version explicitly, or add source straight from a supported repository host:

npx packref add react
npx packref add hono@4.2.0
npx packref add @effect/cli
npx packref add metaideas/packref

Direct repository package specs support these forms:

• GitHub shorthand: owner/repository[/directory][@ref]
• SourceHut shorthand: ~owner/repository[/directory][@ref]
• Provider shorthand: github:owner/repository[/directory][@ref], gitlab:..., bitbucket:..., or sourcehut:...
• Host-prefixed shorthand: github.com/owner/repository[/directory][@ref], gitlab.com/..., bitbucket.org/..., or git.sr.ht/~owner/repository[/directory][@ref]
• Standard Git URL: https://github.com/owner/repository.git[@ref] or git+https://...
• SCP-style SSH URL: git@github.com:owner/repository.git[@ref]

The optional ref can be a tag, branch, or full 40-character commit SHA. If you omit it, Packref uses the default branch and pins its current commit. Direct repository references are manual references.

A project can select one directory for each repository and pinned commit identity. Remove the existing package source reference before selecting another directory for that identity. Different projects can select different directories while they reuse the same full-repository source snapshot.

Running packref add without a package opens a multiselect of dependencies not yet referenced. When a dependency has no installed version in a package-manager lockfile or node_modules, Packref resolves its manifest range against the registry and tells you to install dependencies and sync.

Commit .packref/packref-lock.json with the project. After cloning, restore every locked source reference with:

npx packref install

install follows the committed lockfile exactly. It does not resolve project dependencies, adopt new dependencies, or change lockfile contents.

Commands

Command	Description
packref init	Initialize the current project, create or preserve its lockfile, register it globally, and offer to write ignore rules and agent guidance. Use --non-interactive with --ignore and/or --agents for unattended setup. If a committed lockfile already has entries, run npx packref install afterward to materialize them.
packref add [package]	Add a package source reference from a registry package spec or direct repository package spec. A versionless dependency uses the project's exact installed version when available. Explicit versions and direct repository sources are tracked manually. Omit the package to select unresolved project dependencies interactively.
packref install	Materialize missing source trees from .packref/packref-lock.json. Packref reuses matching global snapshots and fetches missing snapshots from the source metadata in the lockfile.
packref list packref ls	List the current project's references in deterministic order, including the version, source host or tarball type, and a marker for manually tracked entries.
packref remove [package] packref rm [package]	Remove matching project-local source trees and lockfile entries. Omit the package to select from all references. If a name matches multiple versions, Packref asks which versions to remove. For example: npx packref remove react or npx packref remove react@18.3.1.
packref sync	Update existing dependency-tracked references to the exact versions resolved for the project. Remove dependency-tracked references that are no longer in the manifest. Manual references are preserved, and unreferenced manifest dependencies are not automatically adopted.
packref prune	Remove global store entries that no registered project uses. Missing or unreadable registered projects are reported and prevent unsafe pruning. Stale registrations can be removed interactively.
packref clean packref clean --global	Clear all references from the current project and reset its lockfile after confirmation. The --global flag wipes only the global source store; registered projects and project-local state are preserved.

Files and storage

<project>/
└── .packref/
    ├── packref-lock.json  # Committed package identities, versions, source metadata, and tracking modes
    └── packages/          # Ignored project-local package source references

~/
└── .agents/
    └── packref/
        ├── config.json    # Registered project paths used by packref prune
        └── store/         # Deduplicated source snapshots shared across projects

Only .packref/packages/ and temporary lockfile writes should be ignored. The lockfile is the reproducibility boundary and belongs in version control.

Source resolution

For npm packages, Packref prefers repository source when registry metadata points to a supported Git host (GitHub, GitLab, Bitbucket, or SourceHut) and the repository has a tag matching the resolved package version. Repository snapshots retain the repository layout and, when metadata specifies one, the package's monorepo directory.

Packref falls back to the published npm tarball when repository metadata is missing, the repository host is unsupported, or no matching version tag exists. It does not silently fall back when Git is missing or a supported repository download fails, because those are actionable environment or network failures.

Operational boundaries

• Packref currently supports npm packages and JavaScript projects with package.json.
• Fetching repository source requires Git, which Packref uses to discover matching version tags.
• Package-manager lockfiles and node_modules are used to discover exact installed versions; the npm registry is the final resolution fallback.
• Source trees are read-only references for agents, not runtime dependencies.
• Packref assumes one process mutates its project and global files at a time. There is no concurrent writer locking in v1.
• Multiple versions of the same package can coexist.

Agent skill

Install the first-party Packref skill to teach coding agents when and how to inspect the exact local dependency source:

npx skills add metaideas/packref --list
npx skills add metaideas/packref --skill packref

See the packref skill on skills.sh.

Made with 🥐 pastry