github-star-organize

A simple Rust CLI that fetches your GitHub starred repositories and caches them locally as structured JSON.

Current phase: Phase 1 — basic fetcher and JSON cache.
AI-powered organization and description enrichment are planned for a later phase.

Features

• Fetch starred repositories from the GitHub API
• Paginate through all stars automatically
• Cache raw API results locally as JSON
• Use cache on subsequent runs to avoid repeated API calls
• AI-friendly structured output for future enrichment

Installation

Requires Rust.

git clone <repository-url>
cd github-star-organize
cargo build --release

The binary will be available at target/release/github-star-organize.

Usage

Fetch your own stars

Provide a GitHub personal access token:

github-star-organize fetch --token <GITHUB_TOKEN>

Or set the GITHUB_TOKEN environment variable:

export GITHUB_TOKEN=<your-token>
github-star-organize fetch

Fetch public stars for any user

github-star-organize fetch --username octocat

Common options

Option	Description	Default
-u, --username <USER>	GitHub username	authenticated user
-t, --token <TOKEN>	GitHub token (or GITHUB_TOKEN env)	none
-c, --cache <PATH>	Cache JSON path	.github-stars-cache/stars.json
--force	Re-fetch from GitHub	false

Examples

# Default cache path
github-star-organize fetch --token $GITHUB_TOKEN

# Custom cache path
github-star-organize fetch \
  --token $GITHUB_TOKEN \
  --cache .cache/stars.json

# Force refresh
github-star-organize fetch --token $GITHUB_TOKEN --force

Cache format

The cache is a plain JSON file containing metadata and an array of repositories:

{
  "fetched_at": "2026-06-26T03:53:45Z",
  "username": "octocat",
  "repos": [
    {
      "id": 1296269,
      "full_name": "octocat/Hello-World",
      "html_url": "https://github.com/octocat/Hello-World",
      "description": "My first repository on GitHub!",
      "language": null,
      "stargazers_count": 3649,
      "topics": [],
      "starred_at": "2011-01-26T19:01:12Z"
    }
  ]
}

This format is ideal for feeding into an AI for categorization, summarization, or report generation.

Creating a GitHub token

1. Go to GitHub → Settings → Developer settings → Personal access tokens.
2. Generate a classic token.
3. For public stars, no scopes are required — the token simply raises the API rate limit from 60 to 5,000 requests per hour.
4. For private starred repositories, enable the repo scope.

Project structure

├── src
│   ├── main.rs      # CLI entry point
│   ├── lib.rs       # Module declarations
│   ├── cli.rs       # Command-line argument parsing
│   ├── models.rs    # Data structures
│   ├── github.rs    # GitHub API client
│   └── cache.rs     # JSON cache read/write
├── PLAN.md          # Implementation plan
├── AGENTS.md        # Coding guidelines for agents
└── README.md        # This file

Roadmap

• Phase 1: Fetcher and JSON cache
• Phase 2: Optional AI enrichment (categorization, improved descriptions)

License

MIT