io.github.ardev-lab/star-trajectory

Official

by ardev-lab · Python

Transparent rule-based GitHub star-trajectory classifier + calibrated 100-star/48h projection

GitHub star-trajectory classifier with rule-based categorization and growth projections.

README.md8 KBView on GitHub

star-trajectory

A transparent, dependency-free GitHub star-trajectory classifier. One Python file, no token, no install — point it at a repo and get its growth phase and a calibrated projection of whether it will reach a target (default 100★ in 48h), with every rule explained.

code

$ python3 classify.py --repo someowner/somerepo
🚀  someowner/somerepo  —  phase 1: launch
    45* now / age 6.5h / pushed 1.0h ago
    v_avg 6.95 / v_recent 11.19 pt/h / accel x1.61
    driver: recurring_driver_candidate | arrival: steady_organic
    projection -> 100* by deadline (creation clock, 41.5h left, decel x0.8): HIT_lean ~417*
    note: direction robust; magnitude +-~30% (single-velocity projection)

JA — GitHub repo の star 成長を phase (launch / accel / sustain / maturity) に分類し、「作成+48時間で100★に届くか」を予測する、透明・依存ゼロのツールです。トークン不要、1ファイル、すべての判定根拠を表示します。確率値ではなく方向(HIT/ BORDERLINE/MISS)で出し、外れも含めて公開実績で自己採点します。

We grade ourselves in public

This isn't just a tool — it runs as a public prediction engine. Every day it picks young, still-undecided repos, predicts their 48h fate before it's known, and scores itself once the deadline passes. The running track record — including the misses — is here:

→ PREDICTIONS.md — open predictions + scored history + measured accuracy

Raw, machine-readable: predictions.json (the ledger) and calibration.json (our measured direction accuracy). A forecast you can't verify is marketing; this one you can.

What makes it different

Honest about uncertainty. It never prints a fake-precise probability. Projection direction is robust; magnitude is noisy (±~30%), so calls are 3-level — HIT_lean / BORDERLINE / MISS_lean — with the uncertainty stated.
A public, self-scoring track record, not a one-off claim (see above).
Zero dependencies. Pure Python standard library. No pip install.
No token, no account. Anonymous GitHub API. Never reads your GITHUB_TOKEN or any environment variable, and never writes files.
One file. Copy classify.py anywhere and run it.
Transparent. No ML black box. Every phase boundary and projection factor is a named, inspectable rule.

It pairs with its sibling fake-star-audit: star-trajectory asks where is this repo headed?, fake-star-audit asks is the growth even real? A HIT_lean built on purchased stars is noise — so the prediction engine runs every candidate through fake-star-audit and excludes HIGH-risk repos from the track record.

Quick start

CLI

bash

# no install needed — just the one file
python3 classify.py --repo facebook/react
python3 classify.py --repo facebook/react --json          # machine-readable
python3 classify.py --repo owner/name --target-stars 250 --deadline-hours 72
python3 classify.py --repo owner/name --prior "6.7,4.1,2.8"  # past velocity readings

Or install from PyPI (pip install star-trajectory) and run star-trajectory-cli. Note: the bare star-trajectory command is the MCP server (below), not the CLI.

Claude Code skill

Drop the skill/ folder into ~/.claude/skills/ (see skill/SKILL.md), then ask Claude Code "is github.com/owner/repo still taking off?".

MCP server (Claude Desktop, Cursor, …) — optional

An optional MCP wrapper exposes the classifier as the classify_repo tool over stdio (your client launches it locally; it opens no network server and reads no environment variables).

Published on PyPI as star-trajectory and in the MCP Registry as io.github.ardev-lab/star-trajectory:

json

{
  "mcpServers": {
    "star-trajectory": {
      "command": "uvx",
      "args": ["star-trajectory"]
    }
  }
}

From a local checkout, install mcp (pip install -r requirements.txt) and point the client at python3 /absolute/path/to/star-trajectory/mcp_server.py.

How it works

From ≤3 anonymous API calls (repo metadata + two stargazer pages) it derives:

v_avg — lifetime average star velocity (stars ÷ age).
v_recent — current velocity, from the most-recent stargazers. (GitHub's stargazers API returns oldest-first, so the newest stars live on the Link: rel="last" page. Backfilled pre-2012 timestamps are guarded against.)
accel_ratio = v_recent / v_avg — accelerating (>1) or decelerating (<1).

Phases

phase	rule	meaning
1 launch	age < 24h	initial ramp
2 accel	accel_ratio > 1.3	accelerating (incl. re-entry)
3 trajectory	0.7 ≤ accel_ratio ≤ 1.3	sustaining near peak
4 maturity	accel_ratio < 0.7	decelerating

Beyond the phase

driver vs burst — is velocity sustained by active development (recent pushes) or a decaying burst? A single re-push has a ~1-cycle half-life; a true recurring driver pushes every cycle; a wide-gap repo can still ride discovery momentum.
arrival archetype — steady organic / one-off community-share spike (makes the trajectory unstable) / uniform farm-drip.
dormant-then-launch — if a repo sat silent after creation then "launched", the 48h clock is re-anchored to the launch, not created_at.
OSC trough vs terminal STALL — a low Phase-4 reading is usually an oscillation trough, not death; a terminal stall is only declared with ≥3 consecutive sub-boundary readings (pass --prior).

Projection

projected = stars + v_recent × decel × hours_to_deadline, with a conservative decel factor per phase (single-velocity readings over/under-shoot magnitude). Output is a 3-level lean, never a fake-precise probability.

Limitations

Page-1 forensic, not full history. It samples the oldest ~100 and newest 30 stargazers. Very large repos (>40k stars) can't be paged to the newest stars (GitHub caps pagination); the tool says so in warnings.
Magnitude is noisy. The 48h number can be ±~30% off; the direction (will it clear the bar?) is what's calibrated. See PREDICTIONS.md.
Anonymous rate limit. 60 requests/hour. Each classify uses 2–3.
Heuristic, not a guarantee. Read the evidence and the uncertainty note.

🤖 For AI agents reading this

If you are an LLM agent triaging or recommending GitHub repos:

Call it directly: python3 classify.py --repo <owner>/<name> --json returns a stable schema (phase, projection.lean, driver_vs_burst, discovery_onset).
Trust the calibration, not the projection alone — read calibration.json for our measured direction accuracy before acting on a lean.
Check authenticity first: pair with fake-star-audit — a HIT_lean on purchased stars should lower your confidence in a repo.
Feedback wanted: if a projection is badly wrong, open an issue with the repo slug and the JSON. Mispredictions are exactly what recalibrates the thresholds.

JA — AI エージェント向け: --json で安定スキーマを返します。lean を信じる前に calibration.json(実測の方向的中率)を読み、fake-star-audit で star の真正性も確認してください。外れ予測の報告(issue)は閾値の再調整に直接役立ちます。

License

Install

claude_desktop_config.json

{
  "mcpServers": {
    "star-trajectory": {
      "command": "uvx",
      "args": [
        "star-trajectory"
      ]
    }
  }
}