Get GitHub Repository README

Fetch and decode the README content from a GitHub repository.

Usage

npx tsx scripts/readme.ts <repository> [options]

Arguments

Options

Output

README.md from facebook/react
-----------------------------
Size: 12.3 KB
URL: https://github.com/facebook/react/blob/main/README.md

# README Contents

[decoded README content displayed here]

Script Execution (Preferred)

npx tsx scripts/readme.ts <repository> [options]

Options:

• •--token=TOKEN - GitHub Personal Access Token (optional, overrides GITHUB_TOKEN env var)
• •--no-cache - Bypass cache and fetch fresh data from API

Run from the github-api plugin directory: ~/.claude/plugins/cache/github-api/

README API

GET https://api.github.com/repos/{owner}/{repo}/readme

Parameters

Examples

Get README content:

https://api.github.com/repos/facebook/react/readme

Response Format

The response contains README metadata and base64-encoded content:

• •name - README filename (e.g., "README.md")
• •path - Path to the README
• •sha - Git SHA for the file
• •size - File size in bytes
• •url - API URL for the file
• •html_url - GitHub URL to view the README
• •content - Base64-encoded content
• •encoding - Encoding type (always "base64")

README Detection

GitHub automatically detects and prioritizes README files in this order:

1. •README.md
2. •README.markdown
3. •README.rst
4. •README.asciidoc
5. •README.textile
6. •README.creole
7. •README

The API returns the first matching file found.

URL Format Support

The script accepts various URL formats:

• •owner/repo (simple format)
• •https://github.com/owner/repo
• •git+https://github.com/owner/repo
• •git@github.com:owner/repo
• •ssh://git@github.com/owner/repo

Authentication

README access follows GitHub visibility rules:

• •Public repositories: No authentication required
• •Private repositories: Valid token with repo scope required

To access private repositories, provide a GitHub Personal Access Token:

Via environment variable:

export GITHUB_TOKEN=your_token_here
npx tsx scripts/readme.ts private/repo

Via command-line option:

npx tsx scripts/readme.ts private/repo --token=your_token_here

Caching

README content is cached for 1 hour. READMEs change relatively infrequently, so this provides a good balance between freshness and performance.

Use the --no-cache flag to bypass the cache.

Related

• •Use github-repo to get repository metadata
• •Use github-user to get owner profile information
• •Use github-rate-limit to check your remaining API quota

Error Handling

No README found: Not all repositories have READMEs. The API will return 404 if no README file exists.

Repository not found: Verify the owner and repository name are correct.

Private repository: Authentication required for private repositories. Provide a valid token.

Rate limit exceeded: Use a Personal Access Token for higher rate limits.

Use Cases

Package Documentation

Read package documentation from source:

npx tsx scripts/readme.ts facebook/react
npx tsx scripts/readme.ts vercel/next.js

Quick Reference

Get quick reference for a repository:

npx tsx scripts/readme.ts nodejs/node

Private Repository Docs

Access private repository documentation:

npx tsx scripts/readme.ts mycompany/private-repo --token=$GITHUB_TOKEN

Notes

• •README content is base64-encoded and decoded automatically
• •Large READMEs are fully displayed
• •Markdown and other markup formats are displayed in raw form
• •For rendered Markdown, use the HTML URL provided in the output