How It Works

Overview

opensrc resolves packages from their registry, clones the source repository at the correct version tag, and caches it globally. Use opensrc path inside other commands to search, read, or explore the source.

rg "parse" $(opensrc path zod)
→ resolves npm registry → finds GitHub repo + version tag
→ git clone --depth 1 → cached at ~/.opensrc/repos/github.com/colinhacks/zod/v3.24.1/
→ prints path to stdout → rg searches the source

Resolution

When you run opensrc path zod, the following happens:

1. Registry lookup — queries the npm registry for the zod package metadata
2. Repository detection — extracts the repository field from package.json to find the source repo URL
3. Version tagging — maps the installed or latest version to a git tag (e.g. v3.24.1)
4. Shallow clone — runs git clone --depth 1 --branch v3.24.1 for a fast, minimal checkout
5. Cache storage — stores the result in ~/.opensrc/repos/github.com/colinhacks/zod/v3.24.1/
6. Path output — prints the absolute path to stdout (progress goes to stderr so subshells work)

On subsequent runs, steps 1-4 are skipped and the cached path is returned instantly.

Version Detection

For npm packages, opensrc tries to detect the version you're actually using in your project. It checks (in order):

1. node_modules/<package>/package.json
2. package-lock.json
3. pnpm-lock.yaml
4. yarn.lock
5. Falls back to the latest tag from the registry

This means the cached source matches the version in your project, not just the latest release.

Cache Directory

All source code is cached in ~/.opensrc/:

~/.opensrc/
├── repos/
│   └── github.com/
│       ├── colinhacks/
│       │   └── zod/
│       │       └── v3.24.1/
│       └── vercel/
│           └── ai/
│               └── main/
└── sources.json

The OPENSRC_HOME environment variable overrides the default cache location.

Metadata

sources.json tracks metadata for all cached sources:

{
  "packages": [
    {
      "name": "zod",
      "version": "3.24.1",
      "registry": "npm",
      "path": "repos/github.com/colinhacks/zod/v3.24.1",
      "fetchedAt": "2025-01-15T10:30:00Z"
    }
  ],
  "repos": [
    {
      "name": "github.com/vercel/ai",
      "version": "main",
      "path": "repos/github.com/vercel/ai/main",
      "fetchedAt": "2025-01-15T10:30:00Z"
    }
  ]
}

AGENTS.md Integration

opensrc is designed to be referenced in your AGENTS.md file so AI coding agents know how to read source code:

## Source Code Reference

Source code for dependencies is cached at `~/.opensrc/`.

Use `opensrc path` inside other commands to read source:

\`\`\`bash
rg "pattern" $(opensrc path <package>)
cat $(opensrc path <package>)/path/to/file
\`\`\`