opensrc

CLI tool to fetch source code for packages/repos, giving AI coding agents deeper implementation context.

When to Use

• •Need to understand how a library/package works internally (not just its interface)
• •Debugging issues where types alone are insufficient
• •Exploring implementation patterns in dependencies
• •Agent needs to reference actual source code of a package

Quick Start

# Install globally or use bunx
bun add -g opensrc

# Fetch npm package (auto-detects installed version from lockfile)
bunx opensrc zod

# Fetch from other registries
bunx opensrc pypi:requests       # Python/PyPI
bunx opensrc crates:serde        # Rust/crates.io

# Fetch GitHub repo directly
bunx opensrc vercel/ai           # owner/repo shorthand
bunx opensrc github:owner/repo   # explicit prefix
bunx opensrc https://github.com/colinhacks/zod  # full URL

# Fetch specific version/ref
bunx opensrc zod@3.22.0
bunx opensrc owner/repo@v1.0.0

Commands

Output Structure

After fetching, sources stored in opensrc/ directory:

opensrc/
├── settings.json           # User preferences
├── sources.json            # Index of fetched packages/repos
└── repos/
    └── github.com/
        └── owner/
            └── repo/       # Cloned source code

File Modifications

On first run, opensrc prompts to modify:

• •.gitignore - adds opensrc/ to ignore list
• •tsconfig.json - excludes opensrc/ from compilation
• •AGENTS.md - adds section pointing agents to source code

Use --modify or --modify=false to skip prompt.

Key Behaviors

1. •Version Detection - For npm, auto-detects installed version from node_modules, package-lock.json, pnpm-lock.yaml, or yarn.lock
2. •Repository Resolution - Resolves package to its git repo via registry API, clones at matching tag
3. •Monorepo Support - Handles packages in monorepos via repository.directory field
4. •Shallow Clone - Uses --depth 1 for efficient cloning, removes .git after clone
5. •Tag Fallback - Tries v{version}, {version}, then default branch if tag not found

Common Workflows

Fetching a Package

# Agent needs to understand zod's implementation
bunx opensrc zod
# → Detects version from lockfile
# → Finds repo URL from npm registry
# → Clones at matching git tag
# → Source available at opensrc/repos/github.com/colinhacks/zod/

Updating Sources

# Re-run same command to update to currently installed version
bunx opensrc zod
# → Checks if version changed
# → Re-clones if needed

Multiple Sources

# Fetch multiple at once
bunx opensrc react react-dom next
bunx opensrc zod pypi:pydantic vercel/ai

References

For detailed information:

• •CLI Usage & Options - Full command reference
• •Architecture - Code structure and extension
• •Registry Support - npm, PyPI, crates.io details