ghostcite

Catch ghost citations — right DOI, wrong author.

ghostcite is a deterministic, no-LLM command-line tool that cross-checks a bibliography's claimed author and year against CrossRef's canonical record for each DOI. It catches the dominant ghost-citation failure mode — a reference whose cited authorship doesn't match the paper the DOI actually points to — and flags retracted or expression-of-concern works along the way.

The problem

LLM-assisted writing (and plain copy-paste drift) routinely produces references that look right but attribute the cited DOI to the wrong authors or year. A manuscript cites "Li et al. 2024," but DOI 10.3390/plants13060869 is actually Chen et al. A reviewer catches it; an automated check catches it first.

Does the metadata you wrote for this citation match what CrossRef says the DOI actually is?

No model, no API key, no GPU, no download — just CrossRef's REST API and a comparison. It runs in seconds on any CI runner, where the heavyweight LLM-based checkers can't (those need a local GPU — see Related work).

Install

pip install ghostcite          # into the current environment
pipx install ghostcite         # isolated CLI install (recommended)
uv tool install ghostcite      # if you use uv

Usage

ghostcite refs.bib                                    # check a BibTeX file (or .md / DOI list)
ghostcite manuscript.docx                             # or the reference list of a Word manuscript
ghostcite paper.pdf                                   # or of a typeset PDF (pip install 'ghostcite[pdf]')
ghostcite refs.bib --cross-check pubmed               # corroborate against PubMed
ghostcite refs.bib --cross-check pubmed,openalex      # two independent sources of truth
ghostcite refs.bib --badge badge.json                 # write a shields.io citation-health badge
ghostcite refs.bib --json                             # machine-readable output (for CI)
ghostcite refs.bib --fail-on author,year,retraction   # tune the CI gate
cat refs.bib | ghostcite -                            # read from stdin

Input format is auto-detected (BibTeX, Markdown reference list, or bare DOI list); override with --format {auto,bibtex,markdown,doi,document}. A .docx or .pdf is read as a manuscript: the text after its last "References" / "Bibliography" / "Literature Cited" heading is split into entries (numbered lists, author-year, wrapped and hyphenated typeset columns, small-caps surnames), and each entry is checked by DOI when one is printed, else by author + year search. DOCX needs nothing extra; PDF needs pypdf (pip install 'ghostcite[pdf]'). A scanned PDF with no text layer yields no entries, and says so.

Real example — refs.bib cites "Li (2024)" for a DOI CrossRef says is Chen:

$ ghostcite refs.bib
ghostcite: 1 entries, 1 with DOIs
  ✗ A  L1  Li (2024)  →  DOI resolves to Chen (2024) — possibly wrong DOI  [10.3390/plants13060869]
  1 A
$ echo $?
1

  ✗ A   L1    Li (2024)        →  DOI resolves to Chen (2024)…   [10.3390/plants13060869]
  │ │   │     │                    │                               │
  │ │   │     │                    │                               └─ DOI that was checked
  │ │   │     │                    └─ what CrossRef actually records
  │ │   │     └─ what you cited (claimed first author + year)
  │ │   └─ source line in your bibliography
  │ └─ tier: A author · T title · B year · C cosmetic · R retraction · U unresolvable · V venue
  └─ glyph: ✗ fails CI · ⚠ retraction · · informational

How it works

flowchart TD
    A["Citation: claimed author + year (+ DOI)"] --> B{"Has DOI?"}
    B -- yes --> C["GET CrossRef /works/{DOI}"]
    B -- no --> D["CrossRef bibliographic search<br/>(low-confidence)"]
    C --> E{"DOI resolves?"}
    E -- no --> U["Tier U — unresolvable"]
    E -- yes --> F["Compare claimed vs. canonical record"]
    D --> F
    F --> G{"First-author surname matches?"}
    G -- no --> TA["Tier A — author mismatch"]
    G -- yes --> H{"Year matches?"}
    H -- no --> TB["Tier B — year mismatch"]
    H -- yes --> OK["OK"]
    C --> R{"Retracted / expression of concern?"}
    R -- yes --> TR["Tier R — retraction (orthogonal)"]
    F -. "--cross-check pubmed" .-> P["PubMed second opinion"]

No language model is involved at any step. ghostcite resolves each DOI at CrossRef (and optionally PubMed), then does a pure, deterministic comparison of the claimed first-author surname (Unicode-folded, punctuation-stripped) and year against the canonical record, plus a retraction / expression-of-concern check. Only the HTTP client touches the network, via CrossRef's polite pool (a descriptive User-Agent with the project URL, never a personal email).

Use it in CI

A clean run is quiet and exits 0:

Drop in the composite GitHub Action:

- uses: musharna/ghostcite@v1
  with:
    paths: paper/refs.bib
    fail-on: "author,title,year,retraction"

…or the pre-commit hook:

repos:
  - repo: https://github.com/musharna/ghostcite
    rev: v0.4.0
    hooks:
      - id: ghostcite
        # Staged .bib/.md files are appended automatically; args carries flags only.
        args: [--fail-on, "author,title,year,retraction"]

Either way, a finding at or above the --fail-on threshold returns a non-zero exit, blocking the merge or commit before submission.

Offline / reproducible retractions

By default ghostcite reads retraction status from CrossRef live. For a deterministic, byte-reproducible retraction check — with broader coverage than CrossRef's own flags — point it at a Retraction Watch snapshot:

ghostcite fetch-retractions --mailto you@org      # → ~/.cache/ghostcite/retractions.csv
ghostcite refs.bib                                # auto-uses the cached snapshot
ghostcite refs.bib --retraction-db vendor/rw.csv  # or pin an exact snapshot in CI
ghostcite refs.bib --retraction-db none           # force live CrossRef

When a snapshot is active it is the authoritative retraction source (the live CrossRef signal is skipped) and the report names the snapshot in use. The byline/year check still queries CrossRef live — this makes the retraction tier offline and reproducible, not the whole run. Pin a committed snapshot in CI for byte-reproducible results.

Retraction data: Crossref + Retraction Watch (The Center for Scientific Integrity). ghostcite downloads it on demand and does not redistribute it; see NOTICE.

Opt-in semantic claim-support (BYO backend)

ghostcite's defaults are deterministic and need no GPU. If you also want "does the cited paper actually support this sentence?", bring your own LLM:

ghostcite --claims claims.json \
  --semantic-backend openai \
  --semantic-base-url http://localhost:11434/v1 \
  --semantic-model llama3.1

claims.json is a list of {"claim": "...", "doi": "10.x/y"}. Results are abstract-grounded and marked non-deterministic; they never fail CI unless you add --fail-on support.

Scope & limitations

ghostcite's deterministic core checks metadata correctness (does the DOI's record match what you wrote), not deep claim support. It does offer an opt-in, abstract-grounded claim-support check (--semantic, bring-your-own LLM backend, still no local GPU — see above), but that stays intentionally lightweight: full-text entailment, internal-consistency, statistics, and figure checks are a heavier, GPU-bound concern best served by sciwrite-lint. ghostcite deliberately stays on the deterministic, no-GPU side so it can gate every commit and CI run in seconds. It does no auto-fixing and no citation-style linting. CrossRef is the source of truth; --cross-check pubmed adds PubMed as an optional second opinion, and --cross-check pubmed,openalex layers in OpenAlex as well.

• CrossRef stores particle surnames inconsistently (van der Berg vs Berg), so a correctly-cited prefixed surname can rarely produce a Tier A false positive.
• No-DOI entries are resolved by best-effort bibliographic search and flagged low-confidence — treat those as hints, not verdicts. Most PDF reference lists print no DOIs, so a PDF run is mostly this path.
• Manuscript input reads the reference list, not in-text citations; an entry is recognised by an author-shaped line start and a year, so a running footer or an editor's byline that happens to carry a year can appear as one stray unresolved entry.
• Some preprints, datasets, and protocols carry no author metadata in CrossRef and surface as Tier U rather than a mismatch.

License

MIT — see LICENSE.