Agent guide | genome.sh

Hand a local VCF or consumer DNA export to a coding agent. It runs the genome CLI on this machine, fills the A4 template, and writes a PDF. The markdown copy stays at /docs/agent-guide.md for agents that prefer a file.

What the agent should do

Turn a VCF or consumer DNA export into a narrative printable report. The agent runs genome on the user's machine, fills the HTML template, and renders PDF. It does not implement genome.sh, and it does not upload genomes.

Privacy boundary

Never upload raw genomic files to genome.sh. Copy the report template to a private directory before writing personal data.

Data	Where it may go
rsID, gene symbol, HGVS, genomic coordinates	HTTP API, website query, local CLI
VCF / BAM / CRAM / 23andMe / Ancestry / MyHeritage files	Local genome CLI only
Filled report HTML and PDF	Local folder only, never committed
AlphaGenome prediction requests	Opt-in, API-key gated, with an explicit warning

Report template

Sections: about, methodology, five takeaways, dashboard, heart, cancer, longevity, metabolism, immune, brain, physical traits, pharmacogenomics, recommendations, limits, glossary. Optional polygenic-score and trait panels when the file supports them. Status pills: favorable, watch, action, neutral.

Template source

cp -R docs/report-template ~/my-genome-report
cd ~/my-genome-report
# fill report.html, then:
./generate-pdf.sh report.html report.pdf

Install

The crate is genome-sh. The binary is genome. Prefer standard or full for a personal report so gnomAD frequencies are available.

Alternative: conda install -c bioconda genome-sh.

cargo install genome-sh
genome db install standard
genome db status

CLI contract

Formats: human (default), json, compact. Agent scripts should use --format json.

genome query Look up variants by rsID, coordinates, HGVS, or gene.
genome annotate Annotate a VCF against the local database, streaming record by record.
genome compare Compare two genomes for shared, unique, and clinically significant variants.
genome extract Extract variants from CRAM or BAM files.
genome predict Opt-in AlphaGenome effect prediction. Requires an API key and explicit consent.
genome db Install, update, and inspect the local variant database.
genome config Set default format, reference genome, and optional AlphaGenome key.

Examples

genome query rs1799945 --format json
genome query BRCA1 --format json
genome annotate input.vcf.gz --filter clinical --format json

Evidence and medical limits

Do not invent ClinVar significance or frequencies.
Missing markers are not called, not wild type.
A genotyping chip is not whole-genome sequencing and is not a complete BRCA test.
The PDF is informational, not a medical device or a diagnosis.

HTTP API

No authentication. Do not send raw genomes here. Base URL: https://genome.sh

Method	Path	Purpose
GET	/v1/query/:query	Look up variants by rsID, gene name, genomic coordinates, or HGVS notation.
GET	/v1/gene/:gene	List known variants for a gene symbol such as BRCA1.
GET	/v1/gnomad/:rsid	Fetch gnomAD population frequencies for an rsID.
GET	/v1/sources	List bundled annotation sources and versions.
GET	/v1/stats	Return database counts and pipeline freshness.
GET	/v1/health	Health check for the HTTP API.

Copy-ready coding-agent prompt

This is the same text as /agent-prompt.txt. Paste it into a coding agent with a local DNA file.

Open prompt file Markdown for agents

Machine-readable references

License

MIT. Attribution is appreciated but not required.

genome.sh reports public annotations. It is informational software, not a medical device or a substitute for clinical care.

Agent guide for a private DNA report.