|
| 1 | +--- |
| 2 | +name: opensrc |
| 3 | +description: Fetch dependency source code to give AI agents deeper implementation context. Use when the agent needs to understand how a library works internally, read source code for a package, fetch implementation details for a dependency, or explore how an npm/PyPI/crates.io package is built. Triggers include "fetch source for", "read the source of", "how does X work internally", "get the implementation of", "opensrc path", or any task requiring access to dependency source code beyond types and docs. |
| 4 | +allowed-tools: Bash(opensrc:*) |
| 5 | +--- |
| 6 | + |
| 7 | +# Source Code Fetching with opensrc |
| 8 | + |
| 9 | +Fetches dependency source code so agents can read implementations, not just types. Clones repositories at the correct version tag and caches them globally at `~/.opensrc/`. |
| 10 | + |
| 11 | +## Core Pattern |
| 12 | + |
| 13 | +```bash |
| 14 | +rg "parse" $(opensrc path zod) |
| 15 | +cat $(opensrc path zod)/src/types.ts |
| 16 | +find $(opensrc path zod) -name "*.test.ts" |
| 17 | +``` |
| 18 | + |
| 19 | +`opensrc path <pkg>` prints the absolute path to cached source. If not cached, it fetches automatically. Progress goes to stderr, path to stdout, so `$(opensrc path ...)` works in subshells. |
| 20 | + |
| 21 | +## Fetching Source Code |
| 22 | + |
| 23 | +```bash |
| 24 | +opensrc path zod |
| 25 | +opensrc path pypi:requests |
| 26 | +opensrc path crates:serde |
| 27 | +opensrc path facebook/react |
| 28 | + |
| 29 | +# Multiple packages at once |
| 30 | +opensrc path zod react next |
| 31 | +opensrc path pypi:requests pypi:flask |
| 32 | +opensrc path crates:serde crates:tokio |
| 33 | + |
| 34 | +# Specific versions |
| 35 | +opensrc path zod@3.22.0 |
| 36 | +opensrc path pypi:flask@3.0.0 |
| 37 | +opensrc path owner/repo@v1.0.0 |
| 38 | +opensrc path owner/repo#main |
| 39 | +``` |
| 40 | + |
| 41 | +### Version Resolution |
| 42 | + |
| 43 | +For npm packages, opensrc auto-detects the installed version from lockfiles (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`). Use `--cwd` to resolve from a different project: |
| 44 | + |
| 45 | +```bash |
| 46 | +opensrc path zod --cwd /path/to/project |
| 47 | +``` |
| 48 | + |
| 49 | +For PyPI and crates.io, explicit versions or latest are used. For repos, use `@ref` or `#ref` to pin a branch, tag, or commit. |
| 50 | + |
| 51 | +## Managing the Cache |
| 52 | + |
| 53 | +Source is cached globally at `~/.opensrc/` (override with `OPENSRC_HOME`). |
| 54 | + |
| 55 | +```bash |
| 56 | +opensrc list # show all cached sources |
| 57 | +opensrc list --json # JSON output |
| 58 | + |
| 59 | +opensrc remove zod # remove a package |
| 60 | +opensrc remove facebook/react # remove a repo |
| 61 | + |
| 62 | +opensrc clean # remove everything |
| 63 | +opensrc clean --npm # only npm packages |
| 64 | +opensrc clean --pypi # only PyPI packages |
| 65 | +opensrc clean --crates # only crates.io packages |
| 66 | +opensrc clean --packages # all packages, keep repos |
| 67 | +opensrc clean --repos # all repos, keep packages |
| 68 | +``` |
| 69 | + |
| 70 | +## When to Fetch Source |
| 71 | + |
| 72 | +Fetch source when you need to: |
| 73 | +- Understand internal behavior that types don't reveal |
| 74 | +- Debug unexpected library behavior |
| 75 | +- Learn patterns from well-known implementations |
| 76 | +- Verify how a function handles edge cases |
| 77 | + |
| 78 | +Don't fetch source for simple API usage questions that docs or types can answer. |
0 commit comments