gh-viewer

gh-viewer lets you explore GitHub repositories from the command line using the GitHub REST API. It focuses on fast repository discovery and inspection:

• list directories within a repo (--list)
• read file contents with optional line ranges (--read)
• run glob patterns against the repository tree (--glob)
• search accessible and public repositories (--search-repos)
• search code within a repository (--search-code)
• search commit history (--commit-search)
• compare refs with diff stats (--diff)

Motivation

I often use open source repos to compare my solutions with those of someone who has tackled the same problem before, and I like learning how my dependencies work under the hood. Both of these tasks were tedious manually, but were always worth it to get to quality solutions. Nowadays, thanks to Claude Code and Codex, that task is much easier. However, tooling is limited. The problem with GitHub is that the standard fetch tools struggle to see the file tree, and AI agents have to work around JavaScript-heavy file pages by using raw.githubusercontent.com. gh-viewer solves these problems. Just tell your AI agent to learn how to use gh-viewer by invoking gh-viewer -h, and then you can ask it specific questions about your target repo, like "using gh-viewer, please study how useState is implemented in facebook/react, and how I might implement my own from scratch".

Installation

npm install --global @kennyfrc/gh-viewer

Or run directly without installing:

npx @kennyfrc/gh-viewer --help

To hack on the CLI locally without publishing:

npm install
npm run build
node dist/cli.js --help

Authentication

Unauthenticated requests are limited to 60 per hour per IP (GitHub REST API rate limits). Export a personal access token to increase the limit to 5,000 requests per hour.

export GITHUB_TOKEN=ghp_...

See Authenticating to the REST API for token guidance.

Usage

gh-viewer --repo owner/name [--ref main] --list path
gh-viewer --repo owner/name --read path[@start-end]
gh-viewer --repo owner/name --read path --line-numbers
gh-viewer --repo owner/name [--ref main] --glob "src/**/*.ts"
gh-viewer --search-repos --pattern viewer --language TypeScript --limit 20
gh-viewer --repo owner/name --search-code --pattern "createViewer" --path src
gh-viewer --repo owner/name --commit-search --query "fix" --since 2024-01-01
gh-viewer --repo owner/name --diff --base main --head feature --include-patches
gh-viewer --org my-org --list-repos
gh-viewer --user octocat --list-repos

Options

• --repo <owner/repo> — target repository for list/read/glob.
• --org <name> / --user <name> — list repositories for an organization or user.
• --list <path> — list entries at path (default .) in the repository.
• --read <path[@start-end]> — print file contents; optional @start-end limits the line range.
• --glob <pattern> — filter the repository tree with a glob expression (uses minimatch).
• --search-repos — search repositories with optional --pattern, --language, --limit, and --offset filters.
• --search-code — run a code search within the repository (requires --pattern; supports --path, --limit, --offset).
• --commit-search — search commits with optional --query, --author, --path, --since, --until, --limit, --offset.
• --diff — compare refs using --base and --head, optionally --include-patches to embed unified diffs.
• --ref <branch|tag|sha> — override the default branch when resolving content.
• --json — output machine-readable JSON instead of the default transcript.
• --help — print usage help.
• --line-numbers — prefix read output with line numbers for reproducible transcripts.

Programmatic API

import { createViewer, parseRepo } from "@kennyfrc/gh-viewer";

const viewer = createViewer({ token: process.env.GITHUB_TOKEN });
const repo = parseRepo("octocat/hello-world");
const listing = await viewer.listPath(repo, ".", { ref: "main" });

console.log(listing.entries);

Additional helpers let you stay inside GitHub's REST API without cloning:

• viewer.searchRepositories({ pattern, organization, language, limit, offset }) prioritises repos you can access before falling back to public search.
• viewer.searchCode(repo, { pattern, path, limit, offset }) returns snippets grouped by file with surrounding context.
• viewer.searchCommits(repo, { query, author, path, since, until, limit, offset }) surfaces commit metadata.
• viewer.compareCommits(repo, base, head, { includePatches }) returns ahead/behind stats and per-file changes.

Examples

gh-viewer --org e2b-dev --list-repos
gh-viewer --repo e2b-dev/E2B --list packages/js-sdk/src
gh-viewer --repo e2b-dev/E2B --read packages/js-sdk/src/api/index.ts@1-150
gh-viewer --repo e2b-dev/E2B --glob "spec/**/*.proto"

License

Released under the MIT License.

Notes

• Large files (>1 MB) or repositories with many files may require explicit line ranges.