opensrc

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 npx
npm install -g opensrc

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

Fetch from other registries

npx opensrc pypi:requests # Python/PyPI npx opensrc crates:serde # Rust/crates.io

Fetch GitHub repo directly

npx opensrc vercel/ai # owner/repo shorthand npx opensrc github:owner/repo # explicit prefix npx opensrc https://github.com/colinhacks/zod # full URL

Fetch specific version/ref

npx opensrc zod@3.22.0 npx opensrc owner/repo@v1.0.0

## Commands

| Command | Description |
|---------|-------------|
| `opensrc <packages...>` | Fetch source for packages/repos |
| `opensrc list` | List all fetched sources |
| `opensrc remove <name>` | Remove specific source |
| `opensrc clean` | Remove all sources |

## 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

```bash
# Agent needs to understand zod's implementation
npx 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
npx opensrc zod
# → Checks if version changed
# → Re-clones if needed

Multiple Sources

# Fetch multiple at once
npx opensrc react react-dom next
npx 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