GitHub Star Organizer

This repository uses GitHub Agentic Workflows to categorize the authenticated user's starred repositories into their actual GitHub Lists once a week.

It reads stars and existing Lists through GitHub's GraphQL API. The AI files each star into the most suitable of your existing Lists, and a deterministic step validates the plan before calling updateUserListsForItem. Lists are managed manually: create them yourself at https://github.com/stars, and when the AI thinks a new List would help it opens an issue instead of creating one.

Install

Install the package into any GitHub repository with the guided wizard:

gh aw add-wizard yutkat/github-star-organizer

The installer adds the workflow, compiles its lock file, copies the companion uv runtime under .github/workflows/github-star-organizer/, and records its source for future updates. Pull upstream releases later with gh aw update.

Setup

1. Enable GitHub Actions in the repository where the package was installed.
2. Create one classic personal access token with the user scope and save it as the Actions secret STAR_LISTS_TOKEN. It reads stars and Lists and performs the List updates; GitHub Lists mutations reject fine-grained tokens, so this must be a classic token.
3. Create one fine-grained personal access token owned by the same user with only the Copilot Requests permission and save it as the Actions secret COPILOT_GITHUB_TOKEN. It is used solely to authenticate the Copilot engine, which ignores classic tokens.
4. Run Categorize starred repositories manually from the Actions tab once.

Set expirations appropriate for the deployment and rotate the repository secrets before they expire.

See GitHub's documentation for creating a fine-grained PAT.

Behavior

• Runs weekly on Monday at a time distributed by GitHub Agentic Workflows and supports manual dispatch.
• Scheduled runs inspect only stars added during the preceding seven days.
• Manual runs default to the same weekly scope; select full explicitly to process the complete uncategorized backlog.
• Retrieves the token owner's stars and Lists, without a hard-coded username.
• Skips repositories that already belong to at least one List.
• Preserves existing and concurrent List memberships.
• Never creates or edits Lists; new List ideas are filed as issues on this repository (at most one per run).
• Writes classifications directly to GitHub Lists; no Markdown catalog is used.

To avoid sending thousands of stars to the agent at once, each run normally processes up to 500 uncategorized repositories. Repeat manual runs to complete the initial backfill. Run the manual full scope after a failed or disabled scheduled run to recover stars outside the seven-day window.

If you edit the Agentic Workflow source, run gh aw compile and commit the generated .github/workflows/categorize-stars.lock.yml as well.

Development

Python is managed with uv. Run the test suite with:

uv run --frozen python -m unittest -v

GitHub Agentic Workflows and GitHub Lists are evolving features. Recompile and run the workflow manually after upgrading gh-aw.