superdna 🧬

Read the rest of your DNA test, on your own machine. superdna is a Claude Code skill (with a plain-Python CLI underneath) that takes the raw data file your testing company already lets you download and builds a single-file HTML report from it: deep ancestry with the migration story behind your paternal line, physical traits, nutrition, sleep, medication response, and — only if you explicitly opt in — high-stakes health findings.

Everything runs on your machine with plain Python — the file you download from your testing company never goes anywhere, and the finished report is a single HTML file that works offline.

The bundled demo report — a fictional genome. Your own report is built the same way, locally, with a personalized narrative.

• Install and run — start here
  • As a Claude Code skill
  • CLI only, without Claude
  • Deep mode
• Supported input, and where to get your file
• Why this exists
• What's in the report
• Privacy model
• How the analysis works
• Honest limitations
• Contributing a marker
• Development
• Roadmap
• Attribution and license

git clone https://github.com/Wolg/superdna ~/.claude/skills/superdna

Then tell Claude Code: "analyze my DNA file ~/Downloads/MyHeritage_raw_dna_data.csv". Claude parses the file locally with the bundled scripts, asks which (if any) high-stakes topics you want included, writes a personalized narrative from the extracted findings, and opens your report.

Nothing here needs Claude, an account, or an API key. The report you get is the same one, minus the personalized narrative passages.

git clone https://github.com/Wolg/superdna && cd superdna
python3 scripts/analyze.py data/sample_genome.csv --out reports/results.json
python3 scripts/generate_report.py reports/results.json --out reports/report.html
open reports/report.html          # xdg-open on Linux

Swap data/sample_genome.csv for your own raw export when you're ready — the bundled one is a fictional genome so you can see the output first. High-stakes topics stay hidden unless you ask for them:

python3 scripts/analyze.py <your-file> --out reports/results.json \
  --gated alzheimers,parkinsons,hereditary-cancer

A one-time download of ClinVar and PharmGKB (~300MB) builds a local SQLite index and adds genotype-matched drug annotations to your report:

python3 scripts/setup_deep.py     # then re-run analyze.py

Requires Python 3 and nothing else. Both databases are downloaded to your machine; your data never travels the other way.

If you took a DNA test years ago, you probably got an ethnicity breakdown and not much else. The traits, wellness and health reports were a separate purchase, and in some cases they no longer exist to buy — AncestryDNA retired its health product, and companies get acquired or shut down while your data sits with them.

Here's the thing: the lab work was already done. The chip that produced your ethnicity estimate measured hundreds of thousands of positions in one pass, including the ones behind those paid reports. They're sitting in the raw data file your provider lets you download today. What you were being sold was the interpretation — and interpretation comes from public science: ClinVar, PharmGKB, the GWAS Catalog, 1000 Genomes, dbSNP.

superdna brings that public science to your file, on your own machine, instead of shipping your genome to someone's server. It reads what your test already measured and explains it, with a citation on every claim. It is not a clinically validated health report and does not pretend to be — see honest limitations below.

Don't have your raw data yet? Every provider above lets you download it from account settings. If you're buying a test today: a 30x whole-genome sequence (Nebula Genomics, Dante Labs, Sequencing.com) beats any chip — it reads every position instead of a preselected ~0.02%.

• Raw file → parsed by local Python (stdlib only). It never leaves your machine.
• Using the Claude Code skill: Claude sees only the extracted findings (a few hundred marker genotypes + computed summaries), which transit the Claude API like any conversation text. The skill's own rules forbid Claude from reading the raw file. If even that is too much, use the CLI path — then nothing touches any network.
• Deep mode downloads public databases to you; your data never flows the other way.
• Gated findings (APOE etc.) are withheld by analyze.py itself unless consented — they never reach the report generator, the narrative, or Claude.
• The generated report is inert HTML — it loads nothing from the network and phones nothing home.

1. Parse & normalize — five array dialects → one rsID→genotype map. Alleles sorted, hemizygous Y/MT collapsed, no-calls dropped, automatic strand-complement fallback (arrays report the dbSNP plus strand; literature often doesn't).
2. Curated core — 142 markers as JSON data files with per-marker citations (PubMed / PharmGKB / OMIM / SNPedia), plus-strand genotype tables calibrated against real chip output, and evidence-honesty labels ("weak evidence" categories say so).
3. Origins — Y-tree walk over ancestral/derived states (Ensembl-verified alleles) with hierarchical consistency checks; supervised EM admixture over 31 ancestry-informative markers against 1000 Genomes superpopulation frequencies.
4. Deep mode — local SQLite of ClinVar pathogenic SNVs + PharmGKB level 1A–2B clinical annotations, matched to your exact genotypes; PharmGKB's comparative reassurance text ("decreased, but not absent, risk…") is classified apart from actionable signal so the report stays readable.
5. Report — a designed single-file template + results JSON + (optionally) a Claude-written narrative. Every report opens with a methodology section linking its public sources, and every card links its citation.

• Consumer chips are unreliable for rare variants — false-positive rates up to ~40% in that class. Anything concerning needs a clinical-grade confirmation. The report repeats this wherever it matters.
• Admixture from 31 markers is continental-scale; your provider's estimate is finer.
• MyHeritage exports contain no mitochondrial markers (maternal haplogroup honestly reported unavailable). CYP2D6 copy number, HLA typing, and repeat expansions are beyond any array.
• Weak-evidence categories (psychology, some fitness/sleep markers) are labeled as such in the data files and rendered with that framing.
• Nothing here is medical advice.

Most contributions touch exactly one file. Pick the category in data/markers/, add an entry, run the tests, open a pull request:

{
  "rsid": "rs1801133",
  "gene": "MTHFR (C677T)",
  "trait": "Folate metabolism",
  "stakes": "low",
  "genotypes": {
    "GG": {"summary": "Typical MTHFR activity", "effect": "typical"},
    "AG": {"summary": "Mildly reduced activity — of little consequence with adequate folate", "effect": "typical"},
    "AA": {"summary": "Reduced activity — keep dietary folate adequate", "effect": "notable"}
  },
  "citations": [{"label": "Frosst 1995, PMID 7647779", "url": "https://pubmed.ncbi.nlm.nih.gov/7647779/"}]
}

Four house rules, all in service of the report being trustworthy:

• Write genotypes on the plus strand as dbSNP reports them. The analyzer tries the complement automatically, so you don't need both, but getting the primary orientation right keeps ambiguous A/T and C/G markers correct.
• Every marker cites something — a PubMed ID, PharmGKB, OMIM. No citation, no merge.
• Say when the evidence is thin. Put "(weak evidence)" in the trait name and hedge the summary. A confident sentence about a shaky association is the main way tools like this mislead people.
• Set stakes honestly. Use "high" plus a gate_topic for anything life-altering (neurodegenerative risk, hereditary cancer); those stay behind the consent gate.

Add "sex_limit": "female" or "male" for markers that only apply to one sex.

python3 -m unittest discover -s tests   # full suite, stdlib only

Built test-first throughout. The layout:

SKILL.md                  # orchestration instructions for Claude Code
scripts/                  # parse, analyze, haplogroup, admixture, setup_deep, generate_report
data/markers/*.json       # the curated core — add markers here (citation required)
data/haplotree_y.json     # Y-haplogroup tree (Ensembl-verified derived alleles)
data/aim_panel.json       # admixture panel (1000G frequencies, rebuild via build_aim_panel.py)
template/report_template.html
tests/

• v1.1: WGS VCF input (build 38, honest hom-ref/no-call semantics), GWAS Catalog in deep mode, mtDNA haplogroup tree content, more curated markers.

MIT. Marker selection adapted in part from shmlkv/dna-claude-analysis (MIT) — thanks! Data sources: ClinVar (public domain), PharmGKB (downloaded by each user, not redistributed), 1000 Genomes via Ensembl, dbSNP, ISOGG. The bundled data/sample_genome.csv is synthetic — no real person's data ships with this repo.