starred-manager

Finally organize the repositories you starred.

Local-first • Private • Fast • Semantic search

GitHub’s Stars page is weak. Most developers star hundreds of repos and later can’t find anything useful.
starred-manager is a fast, fully local CLI that lets you sync, tag, annotate, search, and semantically discover your starred repositories — without sending anything to the cloud.

---

Demo

Add a short demo GIF here (recommended: 15–25 seconds)

Suggested recording flow for the GIF:

1. starred sync → progress bar finishes with “Synced 847 starred repositories”
2. starred tag add ollama/ollama local-llm favorite
3. starred note set ollama/ollama "Daily driver for local models"
4. starred list --tag local-llm → clean table showing tags + note
5. starred search "llm" → classic results
6. starred index → “Indexed 847 repositories”
7. starred semantic "tools for running models offline" → ranked results with similarity scores

# After recording, place the file at docs/demo.gif and uncomment:
# ![Demo](docs/demo.gif)

How to record a good demo (free tools):

• Terminalizer or Asciinema + convert to GIF
• Or simply use OBS / Kap (macOS) / Peek (Linux)

---

Why this exists

Pain point	How starred-manager solves it
GitHub Stars has almost no organization	Personal tags + notes
Hard to rediscover old starred repos	Fast local search + semantic search
Everything lives in the cloud	100% local SQLite database
No offline access	Fully offline after first sync

---

Features

Core (zero extra dependencies)

• Sync all starred repositories from GitHub
• Add personal tags and notes
• Fast full-text search (name, description, tags, notes)
• Filter by language or tag
• Export to JSON / CSV
• Works fully offline after the first sync
• Simple statistics

Optional Semantic Search

• Local embeddings powered by sentence-transformers
• Natural language queries (“local llm tools”, “rag frameworks”…)
• Completely offline after indexing

---

Quick Start

1. Install

# Recommended
pipx install .

# Or with uv
uv tool install .

# With semantic search support
pip install ".[semantic]"

2. Set your GitHub token

Create a Personal Access Token (classic) with at least the public_repo scope.

export GITHUB_TOKEN=ghp_your_token_here

# Or create a config file
mkdir -p ~/.config/starred-manager
echo "GITHUB_TOKEN=ghp_your_token_here" > ~/.config/starred-manager/.env

3. Sync & start organizing

starred sync

# Organize
starred tag add microsoft/markitdown llm docs
starred note set ollama/ollama "Best local LLM runner I use daily"

# Search
starred search "local llm"
starred list --tag llm
starred list --lang Python

# Semantic search (optional)
starred index
starred semantic "tools for running models offline"

---

Example output

$ starred list --tag llm --limit 5

                          Starred Repositories
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ Full name                  ┃ Language ┃ Stars ┃ Tags         ┃ Note                 ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│ ollama/ollama              │ Go       │ 178k  │ llm, local   │ Daily driver…        │
│ microsoft/markitdown       │ Python   │ 161k  │ llm, docs    │ …                    │
│ ...                        │ ...      │ ...   │ ...          │ ...                  │
└────────────────────────────┴──────────┴───────┴──────────────┴──────────────────────┘

$ starred semantic "offline model runners"

                  Semantic results for 'offline model runners'
┏━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Score ┃ Full name                ┃ Language ┃ Stars ┃ Tags         ┃
┡━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━┩
│ 0.812 │ ollama/ollama            │ Go       │ 178k  │ llm, local   │
│ 0.754 │ ...                      │ ...      │ ...   │ ...          │
└───────┴──────────────────────────┴──────────┴───────┴──────────────┘

---

Commands

Command	Description
starred sync	Pull latest starred repos from GitHub
starred list	List repos (--tag, --lang, --favorite, --limit)
starred search TEXT	Classic search across name, description, tags, notes
starred tag add REPO TAGS…	Add one or more tags
starred tag remove REPO …	Remove tags
starred note set REPO TEXT	Set / update a personal note
starred note clear REPO	Remove note
starred export	Export to JSON or CSV (--format, --output)
starred stats	Show overview + top languages
starred index	Build local embeddings for semantic search
starred semantic QUERY	Natural language search over your stars

---

Data location

Everything stays on your machine:

~/.local/share/starred-manager/starred.db

---

Development

git clone https://github.com/yourusername/starred-manager.git
cd starred-manager
pip install -e ".[dev,semantic]"
starred --help
pytest

---

Roadmap

• Core sync + tags + notes + search
• Semantic search (optional)
• Fuzzy search
• Optional lightweight web UI
• Import / export of tags & notes between machines
• Favorites & archive status in list view
• Watch mode / auto-sync

---

Contributing

Contributions are welcome!

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-improvement)
3. Make your changes
4. Run the tests: pytest
5. Commit with a clear message
6. Open a Pull Request

Ideas that are especially appreciated:

• Better search / ranking
• Fuzzy matching
• Import/export of tags & notes
• Small UX improvements in the CLI
• Documentation and demo assets

Please keep the core tool local-first and dependency-light.

---

License

MIT © starred-manager contributors