opensrc

name

opensrc

description

Give coding agents the actual source code of any dependency. `opensrc path <pkg>` shallow-clones a package at the right version and caches it locally, printing a path you can grep/read — for npm, PyPI, crates.io, and GitHub/GitLab/Bitbucket repos. Use when you need to read a library's real implementation (not just docs) to understand internals, verify behavior, find an undocumented API, debug a dependency, or check what changed between versions. Compose with ripgrep/cat/find.

opensrc — read any package's real source

Overview

opensrc resolves a package to its git repo, shallow-clones it at the matching version tag, and caches it under ~/.opensrc/. opensrc path <pkg> prints the absolute path (fetching on first use, instant cache hit after), so you compose it directly with your normal search tools. It turns "I wish I could read how this library actually works" into a one-liner — grounding answers in the real implementation instead of guessing or relying on docs.

Use it when documentation is thin/stale, when you need to trace a bug into a dependency, confirm a function's real signature/behavior, or diff two versions. For library docs/API reference the context7 MCP is often faster; reach for opensrc when you need the code itself.

Install

npm install -g opensrc      # installs the native Rust binary (no Node overhead per run)
opensrc --version           # v0.7.2 at time of writing

Core pattern: path + your tools

opensrc path emits a directory path; wrap it in $(...):

rg "parse" $(opensrc path zod)                       # search a package's source
cat $(opensrc path zod)/src/types.ts                 # read one file
find $(opensrc path pypi:requests) -name "*.py"      # explore a PyPI package
ls $(opensrc path crates:serde)/src/                 # browse a crate
grep -r "Router" $(opensrc path vercel/next.js)/packages/next/src/   # a GitHub repo

rg "parse" $(opensrc path zod react next)            # several packages at once

This is the idiomatic agent workflow: resolve a path, then ripgrep into it. No manual git clone, no version guessing, no polluting the working project.

Registries & prefixes

Registry	Prefix	Example
npm	(default) or npm:	opensrc path zod
PyPI	pypi: / pip: / python:	opensrc path pypi:requests
crates.io	crates: / cargo: / rust:	opensrc path crates:serde
GitHub	owner/repo or full URL	opensrc path vercel/next.js
GitLab	gitlab: or URL	opensrc path gitlab:owner/repo
Bitbucket	bitbucket: or URL	opensrc path bitbucket:owner/repo

Pin a version

rg "ZodError" $(opensrc path zod@3.22.0)
cat $(opensrc path pypi:flask@3.0.0)/src/flask/app.py

Without @version, opensrc detects the version from your lockfile (npm only) or falls back to the latest tag. Pass --cwd <path> to point lockfile resolution at a specific project so the source you read matches what's actually installed.

Other subcommands

opensrc fetch zod pypi:requests crates:serde vercel/next.js   # pre-warm cache, no path output
opensrc list                # what's cached (human-readable)
opensrc list --json         # machine-readable (parse this in scripts)
opensrc remove zod          # drop one package (alias: rm)
opensrc clean               # wipe cache  (--packages | --repos | --npm | --pypi | --crates)

Flags worth knowing: --verbose (progress during path fetch), --quiet/-q (silence fetch), --cwd (lockfile-aware version resolution).

When to use vs alternatives

• vs reading docs / context7 MCP — opensrc gives you the code; use it when behavior is undocumented, docs are wrong/stale, or you must see the actual implementation.
• vs git clone by hand — opensrc auto-resolves the registry → repo → correct version tag, shallow-clones, and caches globally so repeated lookups are free and don't clutter your project tree.
• vs your installed node_modules/site-packages — those may be built/minified or lack tests; opensrc fetches the real source repo at that version (with tests, comments, history context).
• For your own project's code use normal search; for understanding a dependency use opensrc.

How it works / gotchas

• Cache lives at ~/.opensrc/repos/<host>/<owner>/<repo>/<version>/; metadata in ~/.opensrc/sources.json. Override the location with OPENSRC_HOME.
• Shallow clone at a tag: great for reading a release, but full git history isn't present — don't rely on git log/git blame inside the cache.
• Version detection from lockfiles is npm-only. For PyPI/crates, pin @version explicitly (or with --cwd) when you need an exact match to what's installed.
• First fetch needs network (and may be slow for large monorepos like next.js); cache hits are instant. Pre-warm with opensrc fetch if you're about to do many lookups.
• Resolution depends on the package advertising a source repo and using sane version tags; packages without a public repo or with nonstandard tags may not resolve.
• Requires git on PATH.

Related

Pairs with [[gh-cli]] (authenticated GitHub access for private/raw files), [[graphify]] (turn a fetched codebase into a queryable knowledge graph), and the dev primitives [[pytest]]/[[docker]] when you're tracing behavior into a dependency. Apache-2.0 · github.com/vercel-labs/opensrc