gh-my-starred

A GitHub CLI extension to interactively browse your starred repositories.

Features

• Fuzzy search through all your starred repos with fzf
• JSON output for scripting and analysis with jq
• Smart caching for users with 1000+ stars (auto-detects updates)
• Star lists support — browse curated lists with preserved ordering
• PI extension with native AI agent support (starred_repos, list_star_lists, get_list_repos tools)
• One-key open in browser
• Filter by language, topic, or search query

Table of Contents

• Features
• Installation
• Requirements
• Usage
• Caching
• Star Lists
• PI Extension
• JSON Examples
• Discoverability
• Updating
• Uninstall
• License

Installation

Quick Install

Both (Recommended)

# Terminal CLI
gh extension install kylebrodeur/gh-my-starred

# PI package (AI tools)
pi install npm:pi-gh-my-starred
/reload

What's What

| Component | Install Command | What It Does | |-----------|----------------|--------------| | gh my-starred | gh extension install ... | Terminal CLI, JSON output, fzf browser | | starred_repos | pi install npm:pi-gh-my-starred | AI tool: query your starred repos | | list_star_lists | pi install npm:pi-gh-my-starred | AI tool: discover your star lists | | /starred | pi install npm:pi-gh-my-starred | Interactive fzf in PI (needs CLI above) |

Note: PI tools work standalone. The /starred command needs both because it calls gh my-starred.

Via GitHub CLI Only (Command Line Only)

If you just want the terminal CLI:

gh extension install kylebrodeur/gh-my-starred

Via PI Only (No CLI)

pi install npm:pi-gh-my-starred

For specific versions:

# Specific npm version
pi install npm:[email protected]

# Specific git tag
pi install git:github.com/kylebrodeur/[email protected]

Manual Installation

# Clone
git clone https://github.com/kylebrodeur/gh-my-starred.git

# Make executable
chmod +x gh-my-starred/gh-my-starred

# Link to PATH or use directly
ln -s "$PWD/gh-my-starred/gh-my-starred" ~/.local/bin/

Requirements

• GitHub CLI (gh) - authenticated
• fzf - Only required for interactive mode
• jq - Recommended for JSON parsing

Usage

gh my-starred [options] [limit]

Options

| Option | Description | |--------|-------------| | -h, --help | Show help message | | -v, --version | Show version number | | -j, --json | Output as JSON array (pipeable, no interactive mode) | | --ai | Show AI assistant documentation | | --cache | Force use cached data | | --refresh | Force refresh cache | | --lists | Show all star lists | | --list NAME | Browse a specific star list (preserves order) | | --list-refresh | Force refresh list cache |

Arguments

| Argument | Description | |----------|-------------| | limit | Maximum number of repositories to fetch (default: all) |

Examples

# Interactive mode
gh my-starred              # Browse all starred repos
gh my-starred 100          # Browse last 100 starred repos

# JSON output mode (scriptable)
gh my-starred --json       # Output full JSON of all starred repos
gh my-starred --json 50    # Output JSON of last 50 starred repos

# Documentation
gh my-starred --ai         # Show AI assistant documentation
gh my-starred --help       # Show usage help

JSON Schema

When using --json, each repository object includes:

{
  "full_name": "owner/repo",
  "description": "Repository description",
  "stargazers_count": 123,
  "language": "Python",
  "html_url": "https://github.com/owner/repo",
  "topics": ["cli", "automation"],
  "updated_at": "2025-01-15T10:30:00Z",
  ...
}

JSON Examples

# Filter repos by language
gh my-starred --json | jq -r '.[] | select(.language == "Go") | .full_name'

# Find repos by topic
gh my-starred --json | jq -r '.[] | select(.topics | index("machine-learning")) | .full_name'

# Get top 10 starred repos
gh my-starred --json | jq 'sort_by(.stargazers_count) | reverse | .[:10]'

# Export to CSV
g my-starred --json | jq -r '.[] | [.full_name, .stargazers_count, .language] | @csv' > starred.csv

# Star lists
gh my-starred --lists                    # Show all star lists
gh my-starred --list "Favorites"        # Browse a list interactively
gh my-starred --list "Favorites" --json # Output list as JSON

Interactive Mode

Keys

| Key | Action | |-----|--------| | ↑/↓ | Navigate | | Enter | Open selected repo in browser | | Ctrl-C | Exit |

Caching for 1000+ Stars

With many starred repos, fetching can be slow. gh-my-starred automatically caches and smartly updates:

| Feature | Description | |---------|-------------| | Cache Location | ~/.cache/gh-my-starred/starred-repos.json (respects XDG_CACHE_HOME) | | Smart Updates | Compares starred_at timestamp - only fetches if new stars exist | | Default TTL | 1 hour (3600 seconds) | | Custom TTL | Set GH_STARRED_CACHE_TTL environment variable |

# Force cache refresh
gh my-starred --refresh

# Cache for 24 hours
export GH_STARRED_CACHE_TTL=86400
gh my-starred

Star Lists

GitHub Star Lists allow you to organize starred repos into curated collections. Since GitHub's API does not expose list ordering, gh-my-starred uses HTML scraping to preserve the order in which repos were added to each list.

Discover lists

gh my-starred --lists

Browse a specific list (ordered)

gh my-starred --list "Favorites"
gh my-starred --list "Research" --json
gh my-starred --list "Research" --json 20

List caching

List contents are cached separately at ~/.cache/gh-my-starred/lists/. Use --list-refresh to force a refresh:

gh my-starred --list "Favorites" --list-refresh --json

PI Extension

This repository includes a native PI extension with 4 tools and a command.

Installation

The recommended way is to install it as a PI package (handles extensions + skills automatically):

pi install npm:pi-gh-my-starred

Or via git:

pi install git:github.com/kylebrodeur/[email protected]

Then reload PI with /reload.

Manual Installation (Advanced)

You can also copy the extension file directly, but you won't get updates automatically:

mkdir -p ~/.pi/agent/extensions/
cp .pi/extensions/gh-my-starred.ts ~/.pi/agent/extensions/

Dual-Install Requirement for /starred

The PI tools (starred_repos, list_star_lists, get_list_repos, compare_lists, add_to_star_list) work standalone — they call the GitHub API directly via gh api.

However, the /starred command is an interactive fzf launcher that shells out to gh my-starred. If you run /starred without the CLI extension installed, you'll see a message telling you to run:

gh extension install kylebrodeur/gh-my-starred

Summary: Install the CLI for the terminal, install the PI package for AI tools, or install both for everything.

PI Tools

Once installed, AI agents in PI can use these tools:

| Tool | Description | |------|-------------| | starred_repos | Query and filter all starred repositories | | list_star_lists | Discover all star lists for the user | | get_list_repos | Get ordered repos from a specific star list | | compare_lists | Compare two star lists (shared, unique) | | add_to_star_list | Add repositories to a star list |

Permissions

Some features (like add_to_star_list) require the ability to mutate user lists. If you encounter an INSUFFICIENT_SCOPES error, you must grant the user scope to your GitHub CLI:

gh auth refresh -s user

starred_repos Parameters

| Parameter | Description | |-----------|-------------| | limit | Max repos to return (default: 100, max: 500) | | language | Filter by programming language | | topic | Filter by topic tag | | search | Fuzzy search in name/description | | minStars | Minimum stargazer count | | sortBy | Sort by: stars, updated, name, or starred_at | | refresh | Force refresh cache before querying |

get_list_repos Parameters

| Parameter | Description | |-----------|-------------| | listName | Name of the star list (required) | | limit | Max repos to return | | refresh | Force refresh list cache | | language | Filter by programming language | | topic | Filter by topic tag | | search | Search in name or description | | minStars | Minimum stargazer count | | enrich | Enrich with full metadata from starred cache (default: true) |

PI Command: /starred

Open the interactive fzf browser from within PI:

/starred           # Browse starred repos
/starred 50        # Limit to 50 repos
/starred list "Favorites"  # Browse a specific list

AI Assistant Support

This extension includes built-in documentation for AI assistants. Run:

gh my-starred --ai

This prints guidance for AI agents on how to programatically interact with the extension.

Discoverability

This extension is listed in multiple registries:

• GitHub CLI Extensions: gh extension install kylebrodeur/gh-my-starred
• npx skills: npx skills install kylebrodeur/gh-my-starred
• Claude Code: Auto-discovers .claude/skills/gh-my-starred/SKILL.md
• GitHub Copilot: Auto-discovers .github/skills/gh-my-starred/SKILL.md
• PI Extensions: Auto-discovers .pi/extensions/gh-my-starred.ts
• GitHub Topics: gh-extension, github-cli, fzf, starred-repositories

For AI Agents

AI assistants can discover this tool via:

1. npx skills - Installs via npx skills install kylebrodeur/gh-my-starred
2. SKILL.md (root) - Standard skill format
3. Claude Code skill - .claude/skills/gh-my-starred/SKILL.md
4. GitHub Copilot skill - .github/skills/gh-my-starred/SKILL.md
5. PI extension - Provides starred_repos tool
6. GitHub CLI - Can call gh my-starred --json for JSON output

Related Projects

• fzf - Fuzzy finder used for interactive mode
• gh - GitHub CLI this extension is built for
• PI - AI agent harness with native extension support

Updating

GitHub CLI Extension

gh extension upgrade kylebrodeur/gh-my-starred

PI Package

pi update

Or update just this package:

pi remove npm:pi-gh-my-starred
pi install npm:pi-gh-my-starred
/reload

Both

gh extension upgrade kylebrodeur/gh-my-starred
pi update
/reload

Uninstall

GitHub CLI Extension

gh extension remove kylebrodeur/gh-my-starred

PI Package

pi remove npm:pi-gh-my-starred

Or if installed via git:

pi remove git:github.com/kylebrodeur/gh-my-starred

License

MIT © kylebrodeur