---
name: update-app-count
description: "Workflow for updating the popular LLM applications pool (section/x_llm_apps.md) using get_app_list_by_github_star.py. Covers full refresh, alternate exports, topic tuning, and common pitfalls. USE FOR: Refreshing the ranked GitHub applications list linked from applications.md. DO NOT USE FOR: Hand-curating application entries inside applications.md or adding GitHub star badges to the generated file."
---
## Overview
The pool file `section/x_llm_apps.md` is a generated ranked list of GitHub repositories related to LLM apps, agents, chat UIs, workflow builders, and similar application-layer projects.
It is generated by `code/get_app_list_by_github_star.py` using GitHub topic search, deduplicated across multiple topics, and sorted by GitHub star count descending.
The section `#### Popular LLM Applications (GitHub Stars >= 1000)` in `section/applications.md` links to this generated file with a one-line description only. Do not paste generated entries directly into `applications.md`.
---
## Script Reference
**Script:** `code/get_app_list_by_github_star.py`
**Python env:** `.venv\Scripts\python.exe`
### Key CLI Arguments
| Argument | Default | Purpose |
|----------|---------|---------|
| `--output` | `section/x_llm_apps.md` | Output file path. Extension controls format: `.md`, `.json`, `.csv` |
| `--min-stars` | `1000` | Minimum GitHub star threshold |
| `--topics` | curated list | GitHub topics to query and merge |
| `--token` | `GITHUB_TOKEN` env var | GitHub PAT for higher rate limits |
| `--show` | `30` | Number of repos printed to console |
| `--timeout` | `20` | Per-request timeout in seconds |
| `--max-retries` | `4` | Max retries per request |
| `--backoff` | `1.0` | Initial retry backoff |
| `--sleep` | `1.0` | Delay between successful page requests |
| `--include-archived` | off | Include archived repositories |
---
## Workflow
### 1. Full refresh of the markdown pool
Use this for the normal update path.
```powershell
.venv\Scripts\python.exe code/get_app_list_by_github_star.py
```
- Rewrites `section/x_llm_apps.md`.
- Uses `--min-stars 1000` by default to match the section title.
- Excludes archived repos unless `--include-archived` is passed.
- Writes compact numbered entries instead of badge-heavy markdown.
### 2. Authenticated refresh to avoid GitHub API limits
```powershell
.venv\Scripts\python.exe code/get_app_list_by_github_star.py --token %GITHUB_TOKEN%
```
Use a GitHub PAT when doing a full refresh across many topics. Unauthenticated search is heavily rate-limited.
### 3. Generate a stricter ranking
```powershell
.venv\Scripts\python.exe code/get_app_list_by_github_star.py --min-stars 2000
```
Use this when you want a tighter list. If you change the threshold materially, update the descriptive text in `section/applications.md` so the label stays truthful.
### 4. Export raw data for review
```powershell
.venv\Scripts\python.exe code/get_app_list_by_github_star.py --output files/x_llm_apps.json
.venv\Scripts\python.exe code/get_app_list_by_github_star.py --output files/x_llm_apps.csv
```
Use JSON or CSV when you want to inspect or post-process the ranked repo pool before regenerating markdown.
### 5. Tune the topic set
```powershell
.venv\Scripts\python.exe code/get_app_list_by_github_star.py --topics llm agent rag chatbot ai-workflow
```
- Topics are GitHub repository topics, not free-text queries.
- Results are deduplicated by `full_name` after all topic passes complete.
- If the topic set changes substantially, regenerate the markdown pool rather than editing it by hand.
### 6. Topic-specific doc update
If the output is intentionally narrowed to a subset such as `gemini claude azure-openai copilot assistant`, keep the ranked entries as generated, then update the document metadata and the linking description in `section/applications.md` to reflect the narrowed scope.
---
## Output Format
Each entry in `section/x_llm_apps.md` follows this compact format:
```markdown
1. [owner/repo](https://github.com/owner/repo): Short GitHub description. [Mon YYYY] (⭐ 12,345)
```
- Entries are sorted by GitHub stars descending.
- The date is the repository creation month, formatted as `[Mon YYYY]`.
- The star count is static text in parentheses using the star symbol.
- Do **not** append realtime shields or badges in this generated file.
The file header includes:
- generated timestamp
- GitHub Search API source note
- searched topic list
- total repository count
---
## Common Pitfalls
1. **Using the wrong output target:** The generated ranking belongs in `section/x_llm_apps.md`, not inline inside `section/applications.md`.
2. **Adding GitHub star badges:** This file intentionally uses static text like `(⭐ 12,345)`. Do not run `add_github_stars.py` on it.
3. **Forgetting the star threshold contract:** The linked section title says `≥1000`. If you generate with a different threshold, either restore `1000` or update the section label and description.
4. **Unauthenticated rate limits:** Full runs over many topics can stall or fail without a token. Prefer `GITHUB_TOKEN` for routine refreshes.
5. **Assuming GitHub topics are comprehensive:** Some strong repos do not declare useful topics and may be missed. Expand `--topics` or curate separately if coverage is insufficient.
6. **Archived repos polluting the ranking:** Archived repos are excluded by default. Only include them deliberately.
7. **Hand-editing generated entries:** Manual changes will be lost on the next run. Adjust the script inputs or post-process separately instead.