pi-repos

Read GitHub repositories as if they were local in Pi.

pi-repos gives agents a small set of repository tools for finding GitHub repos, searching code examples, listing files, reading code, finding files by glob, and grepping source. It uses GitHub APIs plus a local archive cache so repeated reads/searches are fast without cloning into your current project.

Installation

From the Pi package catalog / npm:

pi install npm:pi-repos

From GitHub:

pi install git:github.com/liamvinberg/pi-repos

For local development:

pi -e /absolute/path/to/pi-repos
# or
pi install /absolute/path/to/pi-repos

Tools

| Tool | Purpose | | --- | --- | | repo_find | Search GitHub repositories by query. | | repo_code_search | Search code across GitHub for examples, APIs, symbols, or implementation patterns. | | repo_list | List a directory in a remote GitHub repository. Accepts GitHub tree URLs. | | repo_read | Read a file from a remote repository, using cached archives when possible. Accepts GitHub blob URLs. | | repo_find_files | Find files in a remote repository by glob. | | repo_grep | Search file contents in a remote repository with archive + ripgrep acceleration when available. |

Examples

Find the React repository and inspect its package layout.

Find TypeScript examples of virtualized tables across open source projects.

Use repo_grep to search vercel/next.js for createIncrementalCache.

Read README.md from github.com/earendil-works/pi-mono.

Read https://github.com/owner/repo/blob/main/src/example.ts.

Configuration

The extension reads these optional environment variables:

| Variable | Description | | --- | --- | | GITHUB_TOKEN, GH_TOKEN, GITHUB_PAT, GITHUB_PERSONAL_ACCESS_TOKEN | Token for higher GitHub API limits. If absent, the extension tries gh auth token. | | PI_REPOS_CACHE_DIR | Cache root for downloaded repository archives. Defaults to ~/.cache/pi-repos. | | PI_REPOS_REF_REFRESH_MS | How long cached ref-to-commit lookups are considered fresh. Defaults to 5 minutes. |

Development

npm install
npm run check
pi -e .

Notes

• The package uses Pi's package manifest under the pi key and exposes ./src/index.ts as the extension entry point.
• Runtime GitHub archive caches are kept outside the package directory.
• Extensions run with full local permissions; review third-party Pi packages before installing them.