{
  "markdown": "# star-trajectory\n\n<!-- mcp-name: io.github.ardev-lab/star-trajectory -->\n\nA transparent, dependency-free GitHub **star-trajectory classifier**. One Python\nfile, no token, no install — point it at a repo and get its growth **phase** and\na calibrated projection of whether it will reach a target (default **100★ in\n48h**), with **every rule explained**.\n\n```\n$ python3 classify.py --repo someowner/somerepo\n🚀  someowner/somerepo  —  phase 1: launch\n    45* now / age 6.5h / pushed 1.0h ago\n    v_avg 6.95 / v_recent 11.19 pt/h / accel x1.61\n    driver: recurring_driver_candidate | arrival: steady_organic\n    projection -> 100* by deadline (creation clock, 41.5h left, decel x0.8): HIT_lean ~417*\n    note: direction robust; magnitude +-~30% (single-velocity projection)\n```\n\n**JA** — GitHub repo の star 成長を **phase (launch / accel / sustain / maturity)**\nに分類し、「**作成+48時間で100★に届くか**」を予測する、透明・依存ゼロのツールです。\nトークン不要、1ファイル、すべての判定根拠を表示します。確率値ではなく方向(HIT/\nBORDERLINE/MISS)で出し、外れも含めて[公開実績](PREDICTIONS.md)で自己採点します。\n\n## We grade ourselves in public\n\nThis isn't just a tool — it runs as a **public prediction engine**. Every day it\npicks young, still-undecided repos, predicts their 48h fate *before it's known*,\nand **scores itself once the deadline passes**. The running track record —\nincluding the misses — is here:\n\n### → [**PREDICTIONS.md**](PREDICTIONS.md) — open predictions + scored history + measured accuracy\n\nRaw, machine-readable: [`predictions.json`](predictions.json) (the ledger) and\n[`calibration.json`](calibration.json) (our measured direction accuracy). A\nforecast you can't verify is marketing; this one you can.\n\n## What makes it different\n\n- **Honest about uncertainty.** It never prints a fake-precise probability.\n  Projection *direction* is robust; *magnitude* is noisy (±~30%), so calls are\n  3-level — `HIT_lean` / `BORDERLINE` / `MISS_lean` — with the uncertainty stated.\n- **A public, self-scoring track record**, not a one-off claim (see above).\n- **Zero dependencies.** Pure Python standard library. No `pip install`.\n- **No token, no account.** Anonymous GitHub API. Never reads your `GITHUB_TOKEN`\n  or any environment variable, and never writes files.\n- **One file.** Copy `classify.py` anywhere and run it.\n- **Transparent.** No ML black box. Every phase boundary and projection factor is\n  a named, inspectable rule.\n\nIt pairs with its sibling **[fake-star-audit](https://github.com/ardev-lab/fake-star-audit)**:\nstar-trajectory asks *where is this repo headed?*, fake-star-audit asks *is the\ngrowth even real?* A `HIT_lean` built on purchased stars is noise — so the\nprediction engine runs every candidate through fake-star-audit and **excludes\nHIGH-risk repos** from the track record.\n\n## Quick start\n\n### CLI\n\n```bash\n# no install needed — just the one file\npython3 classify.py --repo facebook/react\npython3 classify.py --repo facebook/react --json          # machine-readable\npython3 classify.py --repo owner/name --target-stars 250 --deadline-hours 72\npython3 classify.py --repo owner/name --prior \"6.7,4.1,2.8\"  # past velocity readings\n```\n\nOr install from PyPI (`pip install star-trajectory`) and run `star-trajectory-cli`.\nNote: the bare `star-trajectory` command is the MCP server (below), **not** the CLI.\n\n### Claude Code skill\n\nDrop the `skill/` folder into `~/.claude/skills/` (see [skill/SKILL.md](skill/SKILL.md)),\nthen ask Claude Code *\"is github.com/owner/repo still taking off?\"*.\n\n### MCP server (Claude Desktop, Cursor, …) — optional\n\nAn optional [MCP](https://modelcontextprotocol.io/) wrapper exposes the classifier\nas the `classify_repo` tool over **stdio** (your client launches it locally; it\nopens no network server and reads no environment variables).\n\nPublished on PyPI as `star-trajectory` and in the\n[MCP Registry](https://registry.modelcontextprotocol.io/) as\n`io.github.ardev-lab/star-trajectory`:\n\n```json\n{\n  \"mcpServers\": {\n    \"star-trajectory\": {\n      \"command\": \"uvx\",\n      \"args\": [\"star-trajectory\"]\n    }\n  }\n}\n```\n\nFrom a local checkout, install `mcp` (`pip install -r requirements.txt`) and point\nthe client at `python3 /absolute/path/to/star-trajectory/mcp_server.py`.\n\n## How it works\n\nFrom **≤3 anonymous API calls** (repo metadata + two stargazer pages) it derives:\n\n- `v_avg` — lifetime average star velocity (stars ÷ age).\n- `v_recent` — current velocity, from the **most-recent** stargazers. (GitHub's\n  stargazers API returns *oldest-first*, so the newest stars live on the\n  `Link: rel=\"last\"` page. Backfilled pre-2012 timestamps are guarded against.)\n- `accel_ratio = v_recent / v_avg` — accelerating (>1) or decelerating (<1).\n\n### Phases\n\n| phase | rule | meaning |\n|---|---|---|\n| **1 launch** | age < 24h | initial ramp |\n| **2 accel** | accel_ratio > 1.3 | accelerating (incl. re-entry) |\n| **3 trajectory** | 0.7 ≤ accel_ratio ≤ 1.3 | sustaining near peak |\n| **4 maturity** | accel_ratio < 0.7 | decelerating |\n\n### Beyond the phase\n\n- **driver vs burst** — is velocity sustained by active development (recent\n  pushes) or a decaying burst? A single re-push has a ~1-cycle half-life; a true\n  recurring driver pushes every cycle; a wide-gap repo can still ride discovery\n  momentum.\n- **arrival archetype** — steady organic / one-off community-share spike (makes\n  the trajectory unstable) / uniform farm-drip.\n- **dormant-then-launch** — if a repo sat silent after creation then \"launched\",\n  the 48h clock is re-anchored to the launch, not `created_at`.\n- **OSC trough vs terminal STALL** — a low Phase-4 reading is usually an\n  oscillation trough, not death; a terminal stall is only declared with ≥3\n  consecutive sub-boundary readings (pass `--prior`).\n\n### Projection\n\n`projected = stars + v_recent × decel × hours_to_deadline`, with a conservative\n`decel` factor per phase (single-velocity readings over/under-shoot magnitude).\nOutput is a 3-level lean, never a fake-precise probability.\n\n## Limitations\n\n- **Page-1 forensic, not full history.** It samples the oldest ~100 and newest 30\n  stargazers. Very large repos (>40k stars) can't be paged to the newest stars\n  (GitHub caps pagination); the tool says so in `warnings`.\n- **Magnitude is noisy.** The 48h *number* can be ±~30% off; the *direction*\n  (will it clear the bar?) is what's calibrated. See [PREDICTIONS.md](PREDICTIONS.md).\n- **Anonymous rate limit.** 60 requests/hour. Each classify uses 2–3.\n- **Heuristic, not a guarantee.** Read the evidence and the uncertainty note.\n\n## 🤖 For AI agents reading this\n\nIf you are an LLM agent triaging or recommending GitHub repos:\n\n- Call it directly: `python3 classify.py --repo <owner>/<name> --json` returns a\n  stable schema (`phase`, `projection.lean`, `driver_vs_burst`, `discovery_onset`).\n- **Trust the calibration, not the projection alone** — read\n  [`calibration.json`](calibration.json) for our measured direction accuracy\n  before acting on a `lean`.\n- **Check authenticity first**: pair with\n  [fake-star-audit](https://github.com/ardev-lab/fake-star-audit) — a `HIT_lean`\n  on purchased stars should *lower* your confidence in a repo.\n- **Feedback wanted:** if a projection is badly wrong, open an issue with the repo\n  slug and the JSON. Mispredictions are exactly what recalibrates the thresholds.\n\n**JA** — AI エージェント向け: `--json` で安定スキーマを返します。`lean` を信じる前に\n`calibration.json`(実測の方向的中率)を読み、`fake-star-audit` で star の真正性も\n確認してください。外れ予測の報告(issue)は閾値の再調整に直接役立ちます。\n\n## License\n\nMIT © 2026 ardev. See [LICENSE](LICENSE). Part of the *GitHub repo intelligence*\nsuite — sibling: [fake-star-audit](https://github.com/ardev-lab/fake-star-audit).\n",
  "bytes": 7555,
  "sha": "7bc306ff726a4447c7ffaac2b7914e54b65f7f2d276dc0684807fd84f779712c",
  "repo_slug": "ardev-lab/star-trajectory",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ardev_lab_star_trajectory_a73401bf/readme"
}