StarWhisper: an astronomy skill pack for Codex and Cursor, not a chatbot

What StarWhisper is in 2026: a skill pack, not a model release

The repository began in 2023 as an astronomy language model and now describes itself as a delivery vehicle for skills: 17 research skills that can be installed into Codex or Cursor, together with the data and specifications they operate on. The README states that four of these skills use only the standard library, require no dependencies, no network access and no hardware, and run immediately after cloning. The other 13 are adapted from general research skills covering literature search, hypothesis generation, experiment design, statistical analysis, writing, review, plotting and slides, with the inventory and environment variables listed in skills/README.md.

That framing matters more than the model lineage. StarWhisper 3, the astronomy question-answering and code-writing model, has its training data in LLM_Data/ and its weights on ModelScope under AstroYuYang/StarWhisper3. Version 4.0 is described as still being assembled from popular-science and research text, with weights planned for ModelScope. Nothing in the README says those weights are available now, so a reader arriving for a model download will find the repository has moved on.

The intended user is an astronomer or research engineer who already works inside an agent-based editor and wants domain-specific commands rather than a chat interface. The skills are not a service. They are scripts with subcommands, invoked from a shell or from the agent.

The four zero-dependency skills and what each subcommand does

The README gives a table of tasks mapped to commands. The starwhisper-snclock skill exposes describe, rank, screen, window and audit. The starwhisper-explore skill exposes bar, table and gate. starwhisper-night-plan exposes check-config, budget, lint-targets and endpoints. starwhisper-varlen exposes contract, table, best, compare, labels and check.

The commands that carry the most weight are the ones tied to published tables. screen_snclock.py rank --top 10 selects the youngest supernova candidates from the SN Clock table. screen_snclock.py window --within-days 2 answers whether a given source is still inside its outburst window. screen_snclock.py audit reports how firm the evidence behind a batch of predictions is. On the night-planning side, plan_night.py budget computes how many targets fit in one night, and plan_night.py lint-targets --targets t.csv checks whether a target table is submittable. For sparse light curves, eval_varlen.py best --pool varlen ranks the 11 configurations within a pool, and eval_varlen.py check --csv t.csv verifies a light-curve table against the 3-30 point, 7-class contract.

The skill pack states three rules. Without a key it dry-runs and does not fabricate references. Night planning only checks; it never calls /manipulate_nina or /ftp_transfer under any circumstances. And empty screens, negative verdicts and missing data are reported as they are, rather than loosening conditions to fill a quota. That third rule is the one worth holding the project to, because it is also the one a user can verify by reading the output of audit.

Installing the skills and running a first screen

The README gives a clone followed by an install script, with a separate script for Linux and macOS. The PowerShell form is shown first:

git clone https://github.com/Yu-Yang-Li/StarWhisper.git
cd StarWhisper
powershell -File .\skills\install.ps1

On Linux or macOS the README points to ./skills/install.sh instead. After installation, the first useful run is the SN Clock ranking, which reads the table shipped in snclock/ and prints the youngest candidates:

python .\skills\starwhisper-snclock\scripts\screen_snclock.py rank --top 10

The path separator in the README example is a Windows backslash; on Linux and macOS you would use forward slashes. What you should see is a ranked list drawn from the 22 TNS sources in that table. The second command is the one to run immediately afterward, because it tells you how much the ranking is worth:

python .\skills\starwhisper-snclock\scripts\screen_snclock.py audit

The audit output is where the project is most honest about itself. The README notes that of the 22 sources, only 2 have even the conservative q84 estimate inside two days. If your interest is the night plan rather than the supernova clock, the equivalent first checks are plan_night.py check-config and plan_night.py budget, and for light curves eval_varlen.py contract before eval_varlen.py best.

The SN Clock table and the coverage gap its own data card admits

snclock/ holds one production output: outburst-age estimates for 22 TNS sources at discovery time, reported as q16, q50 and q84 quantiles and split into two bands by whether the estimate falls within two days. The README states plainly that the table's coverage is smaller than the declared screening window, and that for most rows the input snapshots were not retained. That second point is the harder constraint. A prediction without its input cannot be recomputed, so the table functions as a record rather than a reproducible pipeline.

Two further boundaries are stated. The age estimates are not spectral classifications, and every source in the table is already on TNS, so nothing here constitutes a new discovery. Anyone reading the output as a discovery pipeline has misread it.

The Virtual-GOTTA map and SitianClaw are where the README sends readers who want the runnable virtual observatory system. The prototype for true and false sources lives in GOTTA_Prototype/. The repository root is not that system, and the README says so. Sitian itself is described as a plan for 54 one-metre-class wide-field telescopes across several domestic sites, scanning roughly 10,000 square degrees in three colours about every 30 minutes, with StarWhisper positioned as one candidate path for the Sitian brain. That is a plan, not a deployed capability.

Where StarWhisper is the wrong tool

If you need to reproduce a training run, this repository will not get you there. StarWhisper_LC/ contains the light-curve classification tests and the README describes it as not a complete training reproduction. The sparse light-curve training code lives in Early Classification from Sparse Light Curves/, with weights on Hugging Face, and the README warns against quoting 50-point pretraining accuracy as the 3-30 point main result. The varlen skill's own boundary note says comparisons are valid only within the same pool, and that test-set metrics are not outburst times.

If you need an observing agent that talks to hardware, NGSS/ depends on external services including NINA, and the skill pack explicitly refuses to invoke /manipulate_nina or /ftp_transfer. Night planning checks configuration and budget; it does not drive a telescope. The explore/ directory describes a synthetic environment whose environment code is not yet in the repository, so the four verified strategy tables there cannot be regenerated from what is checked in.

There is also a naming hazard. The related searches for this project include a voice app, a scarf, a globe and a YouTube channel. None of those are this repository. A reader searching for an app or a free download will land on the wrong thing entirely; the README's own links go to ModelScope, Hugging Face, a DOI and a GitHub Pages map.

How the skill approach differs from a general research agent

A general-purpose research agent in Codex or Cursor can already read a CSV, write a plot and draft a paragraph. The difference here is that the domain rules are encoded as subcommands with fixed contracts. eval_varlen.py contract states the 3-30 point, 7-class shape a light-curve table must have before eval_varlen.py check will accept it. plan_night.py lint-targets applies a submission check to a target list. screen_snclock.py window answers a question with a day threshold rather than a narrative.

The contrast with a generic agent is that these commands refuse work. The night-plan skill will not transfer files. The SN Clock skill will not call an estimate a classification. The varlen skill will not compare across pools. A general agent asked the same questions would produce an answer; these produce a boundary. That is a real design choice, and it is the reason the skill pack is more useful to a working astronomer than a chat wrapper would be, provided the astronomer wants the boundary.

The cost is coverage. Seventeen skills, four of them standalone, is a narrow surface compared with what a general agent can attempt. The remaining 13 are adapted general research skills rather than astronomy-specific machinery, so the domain depth is concentrated in the four.

Maintenance, licence and what an upgrade actually costs

The repository is not archived and the last push was on 2026-08-19, roughly a month before this writing. The most recent tagged release listed is v0.2.0 from 2023-10-12, so the release tags have not tracked the work described in the README. Anyone pinning to a release tag will get something considerably older than main.

The licence is Apache-2.0, which permits commercial and academic use with the usual attribution and notice requirements. That is a statement about the repository's licence file, not legal advice; if you redistribute the skills or the tables, read LICENSE and CITATION.cff yourself. The README also links a paper in Communications Engineering and a citation file, which suggests citation is expected for the research outputs even where the code licence is permissive.

Upgrade cost is low for the four standard-library skills, since they have no dependency tree to break. It is higher for anything touching NGSS/, where external services including NINA sit between the code and the hardware, and for the sparse light-curve work, where weights live outside the repository on Hugging Face. The README does not document a rollback procedure or a version compatibility matrix, so an upgrade is a git operation against main rather than a managed release path.

Editorial conclusion

Adopt StarWhisper if you want the four standard-library skills, screen_snclock and the night-plan and varlen checkers, and you are willing to trust the published tables rather than regenerate them. Do not adopt it expecting a virtual observatory you can run: the README points to SitianClaw and the Virtual-GOTTA map for that, and the observing agent under NGSS depends on external services such as NINA. Before relying on any number, open snclock/README.md and confirm the coverage gap it describes, then run screen_snclock.py audit on your own checkout and read the evidence column rather than the rank column.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. Yu-Yang-Li/StarWhisper on GitHub