CaskFlow

CaskFlow turns the live Homebrew cask catalog into reviewed, release-ready metadata for CaskHub. It classifies applications, tracks when casks were added, extracts vendor icons safely, and publishes versioned assets that CaskHub can consume with a bundled fallback.

The taxonomy has 17 primary categories and one secondary-only ai trait. Each cask has exactly one primary category and up to two distinct secondary categories. See the classification guide for category boundaries and review rules.

flowchart LR
    brew["Homebrew cask API"] --> diff["Diff and homepage metadata"]
    diff --> classify["Validated classification"]
    classify --> review["Semantic, assigned PR"]
    review --> release["Versioned release assets"]
    brew --> dates["Mine added dates daily"]
    dates --> release
    brew --> icons["Safe icon extraction"]
    icons --> branch["icons branch"]
    release --> caskhub["CaskHub"]
    branch --> caskhub

The daily classification workflow adds new casks, migrates Homebrew token renames, and prunes removed or disabled entries. Provider and validation failures are skipped for a later retry. Results below 0.75 confidence remain in an assigned PR for manual review; higher-confidence updates may auto-merge after required checks pass.

The release workflow runs daily independently of classification, stamps categories.json with its release tag and current icon-token manifest when available, and mines added_dates.json directly from Homebrew's history. Before publishing, it verifies that every cask in the tap's current tree has an added date. A category merge also triggers it immediately. Classification updates therefore do not delay Recently Added data, and date refreshes do not require an LLM result or category assignment.

Icons are downloaded from vendor artifacts, checksum-verified, expanded without running installer scripts, and converted from the application bundle's .icns file. The full safety and audit protocol is in Icon Extraction.

Python 3.12 or newer is recommended.

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Deterministic preview; repository files remain unchanged.
LLM_PROVIDER=mock python scripts/classify_new_casks.py --dry-run

# Test suite and coverage report.
pytest --cov=scripts --cov-report=term-missing

Real classification supports anthropic, openai, groq, and cloudflare; choose one with LLM_PROVIDER and provide that service's credentials. mock is intended for deterministic local verification.

• scripts/ contains the maintained classification, correction, release-data, and icon tooling.
• tests/ covers schema rules and the highest-risk pipeline behavior.
• data/ holds generated reports, caches, and reviewed correction input; it is not the canonical category source.
• .github/workflows/ contains classification, icon, release, and verification automation.

CaskFlow is MIT licensed, so no attribution is required beyond the license terms. If your project consumes CaskFlow data (categories, added dates, or icons), a visible credit with a link back is very much appreciated, for example:

Cask metadata powered by CaskFlow

Bug reports, taxonomy corrections, tests, documentation improvements, and pipeline hardening are welcome. Start with CONTRIBUTING.md, which explains local verification, category correction evidence, and the required semantic PR title format. Pull requests target the develop branch.

MIT