genomi
Use this skill for genetics, genome source, variant, gene, phenotype, disease, screen, pharmacogenomics, and Genomi install/setup maintenance questions.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
Its scripts were only partly scanned.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/exon-research/genomi with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/exon-research/genomi'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/exon-research--genomi)HTML
<a href="/listings/exon-research--genomi"><img src="/api/listings/exon-research--genomi/badge.svg" alt="findsafeskills safety rating" /></a>Install
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 319 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: genomi
- description: Use this skill for genetics, genome source, variant, gene, phenotype, disease, screen, pharmacogenomics, and Genomi install/setup maintenance questions.
- ---
- # Genomi
- Genomi gives agents local tools for genetics and DNA-aware evidence work. Use it
- when the user's request is about variants, genes, phenotypes, disease genes,
- biological screens, medication response, ancestry reference-panel context,
- polygenic-score context, or a
- genome source.
- ## How To Call Genomi
- Call Genomi through the MCP server: `mcp__genomi__<operation>` (or your
- host's equivalent namespace).
- If those tools are missing from the current session's tool list but the
- host's MCP list shows Genomi connected, the session pre-dates the server's
- registration. Ask the user to start a new session.
- ## Core Rules
- - Public by default: if the chat has not mentioned a genome source, answer
- from public/tool sources only.
- - Active Genome Index context is chat-scoped: use it only when this conversation
- provides a genome source, names a previous run, asks about the selected Active Genome Index
- context, or says something like "my Active Genome Index" or "my genome".
- - If the user provides a genome source path in this chat, that is approval to read
- that source for this session.
- - If the user says "my Active Genome Index" or "my genome" without a path, it is acceptable to
- check for an already imported Active Genome Index context.
- - Reading imported/parsed Active Genome Index artifacts, resuming a previous run for
- evidence, or searching for an existing "my Active Genome Index"/"my genome" context requires
- explicit user approval for this session. Record approval with
- `active_genome_index.approve_access` before calling those tools.
- - A configured default user may select an Active Genome Index as metadata, but
- default selection never replaces current-session read approval.
- - Do not use unrelated genome sources from other chats, workspaces, or external
- evaluation tasks.
- - Call narrow tools first and inspect evidence before making a claim.
- - Treat this root skill as static startup guidance. Do not infer live session
- state from it; use `genomi.describe_context`,
- `genomi.check_libraries`, and tool result envelopes for changing context.
- - If an MCP tool returns `status="in_progress"`, call
- `genomi.check_background_job` with the returned `job_id`. Do not retry the
- same work with a capped parse or raw text scan unless the user asks for that
- fallback.
- - Only send parameters supplied by the current user request, current Genomi
- context, a previous Genomi result, explicit user approval, or an explicit
- override. Omit unknown optional parameters.
- - Defaults are part of the reasoning chain. Tool definitions expose
- `parameterDefaults`; returned results include `defaults_applied` for omitted
- defaults so the host agent can inspect and override them in a follow-up call
- when the user intent requires it.
- - Tool definitions expose `dependencyContract` when a tool needs local
- installed libraries or external network/API sources. Missing local libraries
- return `requires_library_install`; unavailable external sources return
- `source_unavailable`; local source-file requirements appear as
- `localResources`.
- - In the final answer, mention Active Genome Index use only when it materially
- affects the result: for example, it supports or refutes a user-specific claim,
- changes a limitation, blocks an operation until approval, or explains a
- required next action. Do not add a routine source-status line.
- - Derive confidence dynamically for each Genomi-guided answer from tool
- evidence, source trust, coverage, conflicts, and missing evidence. Do not use
- a static default confidence or a user-selected confidence profile.
- Genomi result fields describe evidence support, coverage, overlap, and source
- state; they are not final answer-confidence labels.
- - Use `genomi.describe_context` when the user asks about personal context,
- their own genome/context, a genome source, a previous run, a selected user,
- or before making sample-specific claims. When you call it, inspect
- `active_response_profile.guidance`; the active profile id is persisted in
- the Genomi registry (set via `genomi.set_response_profile`) and falls back
- to the catalog default when none is set. Do not call it only to bootstrap a
- public-only question.
- - Handle Active Genome Index lifecycle states yourself. When a read op's
- envelope or `genomi.describe_context` returns
- `active_genome_index_readiness.status == "needs_reparse"`, look up the recorded source
- path under `active_genome_index.agi_intake_source_path` and call `genomi.parse_source`
- with it — routine maintenance, no user prompt needed. Only ask the user
- when `availability.agi_intake_source_path` is false (path moved or deleted) or the
- status is `schema_too_new` (Genomi runtime out of date). Never proceed
- with a stale Active Genome Index while silently substituting placeholder data;
- use the Active Genome Index skill for the full procedure.
- - For search-like operations, pass host-inferred alternate wording in
- `semantic_context` when the current chat reasonably supports alternate
- biomedical wording. Send the user's original wording as `raw_query`, add
- `host_expansions` only as retrieval terms, and add `host_entities` for helpful
- proposed spans such as drug, gene, phenotype, trait_or_condition, variant, or
- rsid. These terms are retrieval inputs, not evidence; Genomi reports
- source/retrieval hits in `term_matches` and no-hit terms in `term_misses`.
- ## Routing
- MCP `tools/list` returns only the default set:
- - Core `genomi.*`, `research.*`, and `journal.*` operations.
- - The complete direct `genomilab.*` host-application boundary.
- - `genomi.invoke` — the dispatcher for every other capability tool.
- Before using a `genomilab.*` operation, load `skills/genomilab/SKILL.md`.
- Those tools keep the current Claude/Codex task in control; they require a
- query-ready selected Active Genome Index, bind patient authorization to the
- current MCP session, and use the portal only for onboarding, exact approvals,
- provider setup, and committed-event monitoring.
- To use a non-base capability tool, load the matching focused capability skill,
- then call:
- ```
- genomi.invoke({"tool": "<operation_name>", "params": {...}})
- ```
- Example:
- ```
- genomi.invoke({"tool": "variant.resolve", "params": {"rsid": "rs429358"}})
- ```
- The dispatcher validates the registered operation name, runs the underlying tool's
- input-schema validation, and returns the underlying tool's response with an
- added `dispatched_tool` field.
- Operation namespaces are tool-name prefixes, not disclosure branches. Use
- namespace filters only for debugging or audits.
- Resolve context, select the intent capability, read its skill markdown, call
- the smallest useful operation through `genomi.invoke` (or direct call for
- base tools), inspect evidence, journal material findings, and continue until
- the answer is supported. Use `genomi.describe_context` only when this chat
- asks about personal context, the user's own genome/context, Active Genome Index
- context, a selected user, a genome source, or a previous run.
- ## Setup
- `genomi.install` installs **or updates** Genomi, and `genomi install` /
- `genomi update` are the same operation. It always updates everything that can
- be updated: the runtime code (`git pull --ff-only` on a git checkout, unless
- `GENOMI_SKIP_RUNTIME_GIT_PULL` is set for a non-git distribution), all public
- reference libraries into `GENOMI_HOME` (idempotent — each installed library is
- checked against its source and re-downloaded only if it changed upstream, so
- re-running transfers nothing when nothing changed; pass `force` to re-download
- regardless), host-agent skill symlinks in detected host skill directories
- (including stale/dangling repair and obsolete Genomi capability-link removal),
- the public retrieval indexes, and a
- background reparse of any genome whose index schema is older than the updated
- runtime's. There are no per-step skip flags — `genomi update` does the full
- update by default. The `libraries` parameter only narrows *which* reference
- libraries to materialize (default `everything`): pass a specific library (or
- comma-separated set) to install just those — both for an install-time subset
- the user chose and to add a single new library on demand at runtime (the
- "install this missing library" path). To see which libraries are already
- installed vs missing before deciding, call `genomi.check_libraries` (its
- summary reports `installed_count` / `missing_count`). This applies once Genomi
- is installed; first-time setup on a machine without the `genomi` runtime
- follows the source bootstrap in `INSTALL_FOR_AGENTS.md`.
- ## Parsing A Genome Source
- `genomi.parse_source` is a core `genomi.*` tool: it detects, parses, and
- digitizes a genome source (VCF/gVCF, BAM, paired-end FASTQ, or a
- consumer-array raw genotype export from 23andMe, AncestryDNA, MyHeritage,
- FamilyTreeDNA, or Living DNA; bare text/CSV, gzip/bzip2/xz-compressed, or
- inside a zip/tar archive; or a `.genome/1.0` bundle such as
- `sample.genome.tar.gz`) into a queryable Active Genome Index.
- - **Use when**: the user supplied a genome source in this chat and downstream
- questions need a queryable Active Genome Index this session.
- - **Why**: raw VCF/BAM/genotype files are too large and irregular for reliable
- direct reasoning; parsing builds the scoped index later tools query.
- - **Not for**: public-only genetics questions, selecting an already-parsed
- index, or capped sample scans that should not replace a complete index.
- - **Result**: digitizes local intake into an Active Genome Index; Genomi
- auto-detects the source type. Supplying `user_nickname` links the parsed
- artifact to a user profile. It does not run whole-callset annotation —
- focused tools materialize public libraries lazily when their evidence is
- needed.
- - If it returns `status="in_progress"` with a `job_id`, poll
- `genomi.check_background_job`; don't substitute a capped parse or raw scan
- unless the user explicitly asks for a fallback.
- - **gVCFs parse in two phases.** A gVCF is ~96% reference blocks, so the parse
- returns as soon as **every variant** is stored and indexed — the result
- reports `variants_ready` (not yet `completed`) and the whole interpretation
- surface (rsID, gene, region, exact-allele lookup, ClinVar, PRS, …) is already
- correct. The reference-block tail is appended by a detached background job
- (`active_genome_index.build_reference_pass`) whose `job_id` is surfaced in the
- result's `next_actions`. Until that job reports `completed`, only "is this
- locus confirmed reference vs not-callable" coverage answers are provisional —
- every readiness/coverage result carries `reference_pending` to say so. Plain
- VCFs, small files, and capped (`max_records`) parses stay single-phase. Other
- sources (consumer arrays, BAM/FASTQ) have no reference tail to defer.
- - **After a parse, offer to name the profile.** When the user did not pass
- `user_nickname`, the result includes an `ask_user` next action: ask them for a
- profile nickname and whether to set it as the machine default, then record it
- by re-running with `user_nickname` (+ `set_default_user=true`) or via the
- invoke-only `active_genome_index.assign_user_genome` / `set_default_user`
- tools — exactly the offer `INSTALL_FOR_AGENTS.md` Step 8 makes.
- The parse/digitize/user-management **workflow** (selecting users, approving
- access, assigning a genome to a profile, lifecycle reparse) lives in the Active
- Genome Index skill, which also owns the
- `active_genome_index.*` interpretation tools.
- ## Journal
- Use journal when an investigation spans multiple Genomi tools and the host
- agent needs to record reasoning over evidence. Journal entries are agent notes
- with traceability links; they are not source evidence and should not be used as
- candidate-ranking `source_records`.
- ## Default Tools
- These tools appear in the default tool list. Their full metadata is available
- without expansion.
- Genomi context and users:
- - `genomi.check_background_job`
- - `genomi.check_libraries`
- - `genomi.describe_context`
- - `genomi.install`
- - `genomi.invoke`
- - `genomi.list_resources`
- - `genomi.search_indexes`
- - `genomi.set_response_profile`
- Active Genome Index:
- - `genomi.parse_source`
- All other `active_genome_index.*` and focused genetics tools are invoke-only:
- reach them via `genomi.invoke` after loading the matching capability skill.
- GenomiLab Research Desk (default-complete):
- - `genomilab.open_workspace`
- - `genomilab.create_investigation`
- - `genomilab.form_specialist_board`
- - `genomilab.report_specialist_progress`
- - `genomilab.record_specialist_report`
- - `genomilab.inspect_investigation`
- - `genomilab.prepare_authorization`
- - `genomilab.record_patient_observations`
- - `genomilab.submit_plan`
- - `genomilab.execute_request`
- - `genomilab.check_request`
- - `genomilab.submit_brief`
- - `genomilab.submit_research_artifact`
- - `genomilab.verify_sequence_substitution`
- - `genomilab.run_esm_substitution_analysis`
- - `genomilab.run_proto_blinded_experiment_design`
- - `genomilab.list_research_artifacts`
- - `genomilab.list_research_tools`
- - `genomilab.revoke_context`
- The agent creates investigations and owns all task lifecycle. The portal must
- not create, message, or cancel an agent task. A repeated local stdio MCP
- initialize is a new agent session and requires renewed patient authorization
- before private investigation state becomes visible. HTTP MCP initialization is
- public-tools-only and cannot create or replace the private GenomiLab runtime.
- Public research:
- - `research.build_target_packet`
- - `research.list_sources`
- - `research.query`
- - `research.record`
- - `research.search`
- Journal:
- - `journal.append_entry`
- - `journal.export_memory`
- - `journal.search_entries`
- - `journal.summarize`
- ## Candidate Evidence
- Candidate and ranking operations return evidence views, `decision_evidence`,
- warnings, and coverage.
- Use source-specific candidate-gene tools instead of a universal comparator:
- `phenotype.compare_gene_hpo_evidence` for HPO/single-subject phenotype
- matching, `gwas.compare_gene_associations` for GWAS Catalog gene-field
- evidence, `phenotype.compare_drug_target_evidence` for drug-target evidence,
- and `functional_genomics.compare_gene_perturbation` for perturbation evidence.
- `phenotype.retrieve_trait_gene_records` retrieves trait-to-gene records from integrated
- sources. Records labelled `association_only_not_causal` are visible evidence,
- not an answer.
- Any operation that exposes an answer-shaped candidate result must expose the
- evidence behind that result. Use that evidence for the host-agent decision.
- ## Multi-Stream Synthesis
- When multiple Genomi capabilities can contribute orthogonal evidence to the
- same question, combine them — both in the initial plan and in follow-ups.
- A scope-limited single-capability result (missing calibration, no record at
- locus, association-only, library-not-installed, low overlap, source
- unavailable, etc.) is not a final user-facing answer when other Genomi
- capabilities can contribute orthogonal evidence to the same question.
- Returning "I cannot answer" while applicable capabilities remain unexamined
- is a host-agent failure mode, not a Genomi limitation.
- When multiple plausible plans differ materially in cost, surface the choice
- once with the tradeoff and commit to the user's pick. Over-checkpointing is
- itself a failure mode.
- ## Answering
- Lead with the answer. When a finding is grounded in a public dataset
- (ClinVar, GWAS Catalog, PGS Catalog, 1000 Genomes panel, etc.) and that
- source materially shapes the result, name the dataset inline in the
- prose. Keep clinical language informational and recommend clinical
- confirmation for medical decisions. Confidence is an answer-time
- synthesis judgment, not static metadata. Adapt explanation depth to the
- selected response profile without weakening evidence limits, privacy
- boundaries, or clinical-confirmation language.
README.md · README · 662 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <p align="center">
- <img src="assets/genomi-logo.png" alt="Genomi logo" width="160">
- <br>
- <strong>Your genome. Decoded.</strong>
- <br>
- <a href="https://www.genomiagent.com/">Website</a>
- ·
- <a href="https://raw.githubusercontent.com/exon-research/genomi/master/INSTALL_FOR_AGENTS.md">Install guide</a>
- ·
- <a href="README.zh-CN.md">简体中文</a>
- </p>
- <p align="center">
- <a href="https://www.python.org/downloads/"><img alt="Python" src="https://img.shields.io/badge/python-3.10%2B-3776AB?style=flat-square&logo=python&logoColor=white&labelColor=111827"></a>
- <a href="https://github.com/exon-research/genomi/releases/tag/v0.1.0"><img alt="Version" src="https://img.shields.io/badge/version-0.1.0-2563EB?style=flat-square&labelColor=111827"></a>
- <a href="https://modelcontextprotocol.io/"><img alt="MCP" src="https://img.shields.io/badge/MCP-agent--native-7C3AED?style=flat-square&labelColor=111827"></a>
- <a href="SKILL.md"><img alt="Skill" src="https://img.shields.io/badge/skill-agent--ready-0E7490?style=flat-square&labelColor=111827"></a>
- <a href="#privacy"><img alt="Local-first" src="https://img.shields.io/badge/privacy-local--first-15803D?style=flat-square&labelColor=111827"></a>
- <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-64748B?style=flat-square&labelColor=111827"></a>
- </p>
- # Genomi
- > Am I going bald? What does my DNA say about Alzheimer's risk? Why does
- > ibuprofen do nothing for me?
- DNA is the layer underneath all of that. It shapes the proteins, enzymes,
- receptors, and pathways behind nutrition, medication response, sleep,
- exercise, inherited traits, and risk for some conditions. Not destiny. But
- the most personal data you carry.
- And it is overwhelming. ~3 billion base pairs, 20,000+ genes, millions of
- observed variants per person. No clinician, no lab, no individual holds that
- in their head. It is too much.
- We live in an era where AI can take on tasks that were not possible before,
- at scales never seen before. Your genome is exactly that kind of task. And
- for the first time, we have the tools to actually read it at the scale it
- lives at.
- Genomi is an open-source AI agent runtime that turns your AI agent into a personal DNA expert.
- Works with Claude Code, Codex, OpenClaw, Hermes, and any MCP-capable host. It gives the agent a private
- workspace: your variants in a local Active Genome Index, public genetics evidence ready to
- query, memory of what you explored, and report tools that turn DNA questions
- into evidence-backed answers. Your genome stays on your machine. The agent
- does the work.
- ## Launch video
- <p align="center">
- <a href="https://youtu.be/8CkoDNlyvZ0">
- <img src="https://img.youtube.com/vi/8CkoDNlyvZ0/maxresdefault.jpg" alt="Genomi launch video" width="640">
- </a>
- </p>
- ## See it in action
- - [Genomi parses your raw DNA file into a local database your agent can query](https://youtu.be/mJUw6Lf8zEk)
- - [Genomi keeps your raw DNA file on your machine](https://youtu.be/Paj2ixdeZGk)
- - [Genomi knows when to say "No" and "I don't know"](https://youtu.be/-yXZhFDiYP0)
- - [Genomi evolves — your agent self-updates to sync with the latest research](https://youtu.be/ih_7elp2H2w)
- ## TL;DR
- Even TL;DR is too long, just paste this to your agent:
- ```text
- Hey please read this and tell me why Genomi is different from other AI
- agent harnesses. Why is this actually useful for understanding my DNA privately?
- https://raw.githubusercontent.com/exon-research/genomi/master/llms-full.txt
- ```
- ## Just Install It
- Install it through your agent. Paste one instruction, answer a few questions,
- and let your agent wire up the runtime:
- ```text
- Install and configure Genomi by following the instructions here:
- https://raw.githubusercontent.com/exon-research/genomi/master/INSTALL_FOR_AGENTS.md
- ```
- The install guide covers dependency checks, library selection, MCP
- registration, optional genome-source import, and verification. If Genomi is
- already packaged or otherwise present, the canonical install/update path is
- `genomi install` or the MCP operation `genomi.install`; the source bootstrap is
- only for hosts that do not have Genomi yet.
- ## GenomiLab Local Research Workspace (Developer Preview)
- GenomiLab is the patient-facing disease-investigation application built on
- Genomi. Ask the Claude Code, Codex, or other MCP host that already runs
- `genomi serve` to open the Research Desk. The same long-lived Genomi MCP process
- owns the session-scoped Active Genome Index handle, GenomiLab domain service,
- encrypted research store, and loopback portal. GenomiLab does not discover or
- launch a second embedded agent server.
- A current Genomi user with a query-ready Active Genome Index (AGI) selected is
- required before the Research Desk opens. Genome intake remains a core Genomi
- setup step: the user can simply give the host agent the local VCF, gVCF, or
- other supported genome-source path, and the agent prepares and selects the AGI.
- On a fresh Genomi home, that path alone creates an immediately usable local
- placeholder profile; the patient can rename it later. Only an existing
- ambiguous multi-user home needs a follow-up choice about which profile owns the
- genome. After that, every GenomiLab investigation reuses the active AGI; it
- never asks for another genome upload or copies AGI rows into its own database.
- The underlying host owns the conversation, native task lifecycle, planning,
- subagents, tool calls, streaming, follow-ups, resume, and cancellation.
- GenomiLab supplies its focused skill, typed patient-research capabilities,
- scoped authorization, durable evidence/hypothesis/brief records, and validation
- at those boundaries. The web portal is for patient onboarding, molecular-profile
- updates, exact approvals, provider setup, and monitoring committed domain
- events. It does not start, message, or cancel a host task.
- For each new investigation, the main host agent chairs a required board of 2–5
- adaptive, non-overlapping native specialist subagents. The chair keeps the
- patient conversation, authorization, private AGI reads, and canonical research
- commits; specialists receive bounded public questions or only the minimum
- approved evidence they need. GenomiLab records the logical board and meaningful
- milestone states for the portal, never raw agent messages, chain of thought, or
- native task identifiers. A resumed investigation reuses its recorded board.
- Follow-up information stays in that same host task and investigation. The host
- records the new patient observation, the patient approves the exact context
- change in the portal, and the host reruns only affected evidence before
- committing a superseding hypothesis and revised brief.
- Those GenomiLab capabilities go beyond both base Genomi and a general harness:
- they project an approved Patient Molecular Profile, preserve source-separated
- disease evidence, relate public findings to exact patient observations, and
- maintain hypotheses, counterevidence, gaps, confirmation needs, and versioned
- patient/clinician briefs. Paperclip supports a narrow, approved set of
- literature, regulatory, and trial-registry discovery operations. It does not
- provide full-text extraction or claim verification. A Paperclip API key can be
- saved securely and checked with a fixed public `TP53`/PMC/one-result probe, but
- that check alone enables no evidence operation. Investigation use still
- requires the applicable owner-provided deployment policy, patient-data
- contract, and exact just-in-time disclosure approval; without that
- configuration, GenomiLab advertises no live Paperclip route.
- Biohub ESM and Proto connection checks remain setup checks and never count as
- scientific execution. GenomiLab separately exposes one bounded ESM
- reference-versus-substitution operation and one bounded Proto blinded
- experiment-design operation only when their respective configured executors
- are local and network-disabled. If an executor is absent, the operation is
- explicitly `unavailable` and creates no artifact. Completed outputs are
- immutable, round-bound nonclinical research artifacts, not evidence: they
- cannot support hypotheses, brief claims, answer-readiness, treatment content,
- or clinician export.
- Deployment owners select installed scientific executors by setting
- `GENOMILAB_ESM_SCIENTIFIC_EXECUTOR` and/or
- `GENOMILAB_PROTO_SCIENTIFIC_EXECUTOR` to an exact entry-point name registered
- under the fixed `genomi.scientific_executors` Python entry-point group before a
- fresh MCP session starts. These values are non-secret names, not import paths
- or commands. Unset selectors keep the operation unavailable; an invalid,
- missing, ambiguous, broken, or non-callable selection fails the new
- GenomiLab runtime closed.
- Deployment owners who have those Paperclip policy records set
- `GENOMILAB_PAPERCLIP_AUTHORIZATION_CONFIG` to the strict JSON policy file before
- the MCP host starts `genomi serve`. The file contains policy and contract
- records, never the API key; the patient saves that credential in the portal.
- The host can inspect those truthful states with
- `genomilab.list_research_tools`; credentials and connect/disconnect actions
- remain in the patient portal.
- Provider secrets and the GenomiLab database encryption key use the native OS
- credential store. The research records themselves stay in encrypted SQLite;
- the credential store holds only key material, so a database copied without the
- local OS account's key is not readable. This is a different requirement from
- the core AGI/query stores, which hold local genomic query artifacts under their
- own access boundary and are never duplicated into GenomiLab.
- The portal binds to a random loopback-only address and opens with a one-time
- private launch link. Each investigation uses an immutable, consented molecular
- profile snapshot, an exact AGI revision, and a bounded genomic scope. Access is
- revoked when the Genomi MCP workspace session ends or the current Genomi user
- changes. Each local stdio MCP `initialize` handshake starts a new GenomiLab
- workspace session and closes any prior one in that process, even when the
- client name and version are unchanged; hosts should not reinitialize the stdio
- connection in the middle of an investigation turn. HTTP MCP initialization is
- public-tools-only and cannot create or replace the private GenomiLab runtime.
- Durable investigation records remain, but a new private session must renew
- private-context authorization before reading them.
- Optional external providers and biological models are behind explicit
- eligibility and patient-data disclosure gates; connection verification never opens a
- patient-informed route, and unavailable capabilities fail closed.
- This remains a research-support developer preview, not a diagnosis or treatment
- product. Findings and proposed clinical implications require appropriate
- clinical confirmation and review.
- ## Works With Every Agent
- Genomi is not tied to one chat app. Any agent host that can use MCP tools,
- local commands, or installed skills can talk to the same local Genomi runtime.
- | Host family | How Genomi connects |
- | --- | --- |
- | Claude Code | MCP server plus Genomi skills |
- | Codex CLI | MCP server plus Genomi skill |
- | OpenCode, OpenClaw, Hermes | MCP server plus host skill where supported |
- | Cursor, Gemini CLI, Cline, Goose, Roo Code, Windsurf, Claude Desktop | MCP server |
- | Any other MCP-capable host | `genomi serve` over stdio |
- One local Genomi home can hold the public libraries, Active Genome Index
- records, score caches, and journals. Session access still follows Genomi's
- approval rules, but the underlying evidence workspace is reusable across host
- agents.
- ## Or If You Prefer The Old-School Way
- Clone, install, point your MCP-capable agent at it. Same flow the installer
- script runs, just done by hand. The
- [install guide for agents](INSTALL_FOR_AGENTS.md) is the canonical reference —
- if anything below drifts from it, that doc wins.
- 1. **Get the source.**
- ```bash
- git clone git@github.com:exon-research/genomi.git ~/.genomi/genomi
- cd ~/.genomi/genomi
- ```
- 2. **Install the package + public libraries.** The recommended install grabs
- every default reference library so Genomi can answer real questions without
- stopping later to fetch missing data. Use a smaller purpose from the catalog
- only when disk, bandwidth, or time is constrained (`common-questions`,
- `medication-response`, `ancestry-context`, `sequence-and-regions`,
- `cell-and-tissue`, `everything`, or `setup-only`):
- ```bash
- export GENOMI_HOME=~/.genomi
- python3 scripts/install_for_agents.py --libraries everything
- ```
- The installer creates a stable command at `$GENOMI_HOME/bin/genomi`.
- Add it to PATH if you want `genomi` available from any shell:
- ```bash
- export PATH="$GENOMI_HOME/bin:$PATH"
- ```
- Once the `genomi` command exists, use it for install/update:
- ```bash
- genomi install --libraries everything
- ```
- 3. **Register the MCP server with your host agent.**
- ```json
- {
- "mcpServers": {
- "genomi": {
- "command": "/absolute/path/to/GENOMI_HOME/bin/genomi",
- "args": ["serve"]
- }
- }
- }
- ```
- For a source checkout where the stable shim is unavailable:
- ```json
- {
- "mcpServers": {
- "genomi": {
- "command": "bash",
- "args": ["-lc", "cd /path/to/genomi && PYTHONPATH=src python3 -m genomi serve"]
- }
- }
- }
- ```
- Reload your host's MCP servers. For URL-based ingestion, `llms.txt` is the
- compact public map and `llms-full.txt` is one inlined reference file.
- ## Ask It Things Like
- Once Genomi is wired up, you talk to the agent like this. In Codex, use
- `$genomi` instead of `/genomi`. The quick stuff first:
- > `/genomi` What does my DNA say about Alzheimer's risk?
- >
- > `/genomi` Am I at risk for early heart disease?
- >
- > `/genomi` Am I going bald?
- >
- > `/genomi` Am I a fast or slow metabolizer?
- >
- > `/genomi` Should I worry about diabetes?
- >
- > `/genomi` Am I lactose intolerant?
- >
- > `/genomi` Is alcohol bad for me specifically?
- Then hand it something bigger:
- > `/genomi` I'm about to start an SSRI. Walk me through my CYP2D6 and
- > CYP2C19 status, what the major guideline sources say about dosing, and
- > what's preliminary vs actually actionable.
- > `/genomi` Run a pharmacogenomic review across every medication I take.
- > Lead with guideline-backed dose adjustments. Flag lower-evidence signals
- > second. Tell me what's outside scope.
- > `/genomi` Build me a one-page rare-disease workup for my HPO terms.
- > Rank candidate genes by source-backed evidence, cite each call, and
- > show me what's missing before this is worth taking to a clinician.
- Or just hand it the whole thing:
- > `/genomi decode`
- One command. The agent sweeps every dashboard capability across your genome —
- variants, ClinVar, pharmacogenomics, ancestry, polygenic scores, and
- nutrigenomics — and serves the result as a self-contained dashboard on
- localhost. Open the URL in a browser.
- Behind those, Genomi gives the agent grounded tools across 20,000+ human
- genes, millions of genotype observations from your file, and the public
- evidence sources that keep the answer honest.
- ## What Genomi Provides
- | Layer | What you get |
- | --- | --- |
- | Active Genome Index | A local, queryable ledger of alleles, zygosity, quality, depth, filters, and callability context from your genome source. |
- | Evidence Library | Focused tools for variants, ClinVar, GWAS, HPO, pharmacogenomics, ancestry context, PRS, and sequence utilities. |
- | Journal | A running log of what you explored, what mattered, and which evidence supported it. |
- | Skills | Agent instructions for routing questions, asking for approval, preserving source priors, and answering clearly. |
- ### Bringing your own genome
- Genomi reads your DNA from wherever it already lives. Point it at any VCF or
- gVCF you have on disk — clinical exports, research callsets, anything that
- follows the spec — and the rest of the pipeline reuses the same Active
- Genome Index regardless of where the file came from.
- Direct-to-consumer providers are supported natively too. Hand Genomi the
- deliverable straight from your account export and it figures out the rest:
- - **23andMe**, **AncestryDNA**, **MyHeritage**, **FamilyTreeDNA** (Family
- Finder), and **Living DNA** — raw genotype text/CSV as exported by the
- provider, including gzip/bzip2/xz-compressed files and zip/tar archives.
- - **genome.computer** — `.genome/1.0` bundles with `manifest.json`,
- `schema.json`, and partitioned `variants.parquet` records.
- - **Nebula Genomics**, **Dante Labs**, and **Sequencing.com** — their VCF
- deliverables are recognized and tagged with the originating provider.
- - **Nebula / Dante / Sequencing.com FASTQ** — paired-end raw reads are
- aligned locally from sibling R1/R2 files or a zip/tar archive containing
- the pair (minimap2 for long reads, bwa-mem2 for short reads), sorted, and
- then fed into the same BAM → derived-VCF path. The `wgs-alignment`
- install purpose pulls down both aligners.
- ### No DNA file yet? Try a public one
- If you don't have your own genome yet but want to see what Genomi actually
- does, the [Personal Genome Project — Harvard Medical School](https://my.pgp-hms.org/public_genetic_data)
- publishes real consumer-DNA deliverables from real participants. Their
- catalog includes public examples for the common consumer-array, VCF, gVCF,
- BAM, and paired FASTQ shapes above; the checked public inventory did not
- include a Living DNA example, even though Genomi supports that export shape.
- Pick a matching participant export, point Genomi at it, and ask questions.
- It is the cleanest way to kick the tires without sequencing yourself.
- Genome data is optional for core Genomi public-only genetics questions. A
- query-ready selected Active Genome Index is required to open GenomiLab.
- ## Why We Built This
- I built Genomi because I want AI to take on the things it never could before,
- at the scale it never could before — and DNA is exactly that.
- A single human genome is overwhelming. Labs spend careers on one gene. Reports
- flatten thousands of variants into a single line. Even the best clinician
- cannot hold 20,000+ genes and millions of genotype observations in their head.
- That is not a limitation of effort. It is a limitation of scale. And it is
- the kind of limitation AI is finally good enough to push against.
- I want this for my own health. I want it for my family's health. And I want
- it to be honest — grounded in real evidence, local by default, with the agent
- showing its work instead of guessing from memory.
- Raw genome files stay on your machine. Genomi is a workspace, not a static
- PDF report. Answers trace back to a source record or they don't get to call
- themselves answers. And the whole thing is built for agents over MCP from
- the start, not bolted on after.
- Generic AI can explain genetics. It should not guess when the question
- depends on an exact variant, your genome file, a guideline source, or a
- coverage limitation. Genomi gives the agent the tools for the parts that
- need evidence, and stays out of the way for the rest.
- ## What Genomi Can Help Explore
- Genomi is not a static report. It is a private workspace your agent can use to
- ask better questions across different parts of your genome.
- - Traits and everyday responses: lactose, caffeine, alcohol, taste, nutrition,
- sleep, exercise, and similar personal questions.
- - Medication response: genes and variants that may affect how your body handles
- specific drugs.
- - Carrier and inherited-risk context: exact variant checks, ClinVar assertions,
- and gene-disease evidence.
- - Common-trait research: GWAS and published score context for complex traits,
- with clear limits.
- - Rare-disease and phenotype review: HPO terms, gene-disease validity, and
- source-backed candidate comparisons.
- - Ancestry reference-panel context: qualitative reference-panel similarity and
- overlap checks, not race or ethnicity prediction.
- - Reports and memory: cited Markdown reports and a journal of what you explored,
- what mattered, and what still needs follow-up.
- ## How Genomi Keeps Answers Honest
- DNA questions can be personal, messy, and easy to overstate. Genomi keeps the
- pieces separated so an agent can show its work.
- - Your genome evidence: genotype, zygosity, depth, quality, filters, exact
- allele observation, and callability.
- - Public evidence: ClinVar assertions, population frequencies, GWAS records,
- gene-disease validity, phenotype annotations, and source versions.
- - Reviewed findings: narrow source-backed notes recorded for a specific target
- or question.
- - Agent memory: observations, decisions, unresolved questions, and links back to
- evidence.
- - Personal context: optional phenotype, medications, family history, or other
- details you choose to provide.
- Different evidence families can point in different directions. Genomi helps the
- agent compare them without pretending that one database is the whole truth.
- ## Privacy
- Genomi keeps the most sensitive data close to you.
- - Raw genome sources stay on the user's machine.
- - Genomi creates Active Genome Index records for personal genome files locally so agents query only the
- variants needed for the current question.
- - Genomi asks for current-session approval before read operations use any
- existing Active Genome Index artifact. A configured default user is
- auto-selected as metadata, but that selection does not approve a private
- read.
- - Public lookups use selected targets such as rsIDs, genes, drugs, conditions,
- or guideline questions.
- - Journal entries are agent-authored memory, not evidence.
- - Project journals reject private/sample evidence links.
- - Memory exports omit private evidence links unless explicitly requested and
- approved.
- ## Sources, Libraries, And Attribution
- Genomi talks to trusted, verified databases and specialist genomics tools so
- your agent can ground answers in real evidence instead of vibes. Install-time
- downloads write source manifests where possible. Live adapters return source
- URLs and access context in their result envelopes. Reviewed source families are
- not treated as background knowledge; agents cite or journal the specific source
- records they used.
- Installed Genomi libraries:
- - [ClinVar](https://www.ncbi.nlm.nih.gov/clinvar/docs/downloads/) —
- `clinvar-grch38` and `clinvar-grch37` VCF caches for exact variant
- interpretation lookup.
- - [Human Phenotype Ontology](https://obophenotype.github.io/human-phenotype-ontology/annotations/) —
- `hpo` phenotype-to-gene and disease annotation files.
- - [GenCC](https://search.thegencc.org/download) — `gencc` gene-disease
- validity submissions.
- - [UCSC Genome Browser downloads](https://hgdownload.soe.ucsc.edu/downloads.html) —
- `reference-grch38` and `reference-grch37` hg38/hg19 FASTA files for
- sequence, normalization, and callability workflows.
- - [UCSC liftOver chain files](https://hgdownload.soe.ucsc.edu/downloads.html#liftover) —
- `liftover-chains` for GRCh37/GRCh38 coordinate translation.
- - [GENCODE](https://www.gencodegenes.org/human/) — `gencode-grch38` and
- `gencode-grch37` transcript annotation GTFs.
- - [ENCODE SCREEN](https://www.encodeproject.org/software/screen/) —
- `encode-ccre-grch38` candidate cis-regulatory element annotations.
- - [PanglaoDB](https://panglaodb.se/markers.html?cell_type=%27all_cells%27)
- and [CellMarker 2.0](http://bio-bigdata.hrbmu.edu.cn/CellMarker/) —
- `panglaodb-markers` and `cellmarker-human` marker tables.
- - [MSigDB Hallmark](https://www.gsea-msigdb.org/gsea/msigdb/human/collections.jsp#H) —
- `msigdb-hallmark`, installed only from a user-supplied official GMT export
- or URL.
- - [PharmCAT](https://pharmcat.org/) and
- [PharmGKB](https://www.pharmgkb.org/) — `pharmcat` all-in-one JAR for
- pharmacogene diplotypes, phenotypes, and recommendation artifacts.
- - [1000 Genomes 30x GRCh38](https://www.internationalgenome.org/data-portal/data-collections/30x-grch38.html) —
- `ancestry-1000g-30x-grch38` compact ancestry PCA panel, distributed from
- the [genomi-ancestry-panel](https://github.com/exon-research/genomi-ancestry-panel)
- build project. `ancestry-1000g-30x-grch37` is derived locally from that
- panel with UCSC liftOver chains.
- - [minimap2](https://github.com/lh3/minimap2) and
- [bwa-mem2](https://github.com/bwa-mem2/bwa-mem2) —
- `minimap2-binary` and `bwa-mem2-binary` for optional FASTQ alignment.
- BAM/FASTQ workflows also use [samtools and bcftools](https://www.htslib.org/)
- when those tools are needed on the host.
- Live public adapters and configured public data:
- - [gnomAD](https://gnomad.broadinstitute.org/) population frequency lookups.
- - [GWAS Catalog](https://www.ebi.ac.uk/gwas/) association-record retrieval.
- - [PGS Catalog](https://www.pgscatalog.org/) score metadata and scoring files.
- - [ClinPGx](https://www.clinpgx.org/), [PharmGKB](https://www.pharmgkb.org/),
- [PGxDB](https://pgx-db.org/), [CPIC](https://cpicpgx.org/guidelines/),
- and FDA [pharmacogenomic biomarker](https://www.fda.gov/drugs/science-and-research-drugs/table-pharmacogenomic-biomarkers-drug-labeling/)
- and [pharmacogenetic association](https://www.fda.gov/medical-devices/precision-medicine/table-pharmacogenetic-associations)
- tables for pharmacogenomic guideline, label, and association context.
- - [KEGG](https://www.kegg.jp/kegg/pathway.html),
- [Reactome](https://reactome.org/),
- [QuickGO](https://www.ebi.ac.uk/QuickGO/),
- [Human Protein Atlas](https://www.proteinatlas.org/), and
- [ChEMBL](https://www.ebi.ac.uk/chembl/) for pathway, ontology,
- tissue/cell-type, compound, and drug-target relationships.
- - [Open Targets Platform](https://platform.opentargets.org/) for disease and
- clinical drug-target context.
- - [BioGRID ORCS](https://orcs.thebiogrid.org/),
- [DepMap](https://depmap.org/portal/download/), and
- [NCBI GEO](https://www.ncbi.nlm.nih.gov/geo/) for configured or discovered
- functional-genomics perturbation evidence.
- Reviewed source families:
- - [ClinGen Gene-Disease Validity](https://search.clinicalgenome.org/kb/gene-validity),
- [GeneReviews](https://www.ncbi.nlm.nih.gov/books/NBK1116/),
- [MONDO](https://mondo.monarchinitiative.org/),
- [Orphanet](https://www.orpha.net/), [OMIM](https://www.omim.org/),
- [GeneCards](https://www.genecards.org/), [MalaCards](https://www.malacards.org/),
- [NCI cancer genetics resources](https://www.cancer.gov/about-cancer/causes-prevention/genetics),
- and the [COSMIC Cancer Gene Census](https://www.cosmickb.org/knowledgebase/cosmic-modules/)
- are source families agents may review, cite, and journal for disease,
- cancer-risk, and gene-context investigations.
- - [DrugBank](https://go.drugbank.com/),
- [PharmaProjects](https://pharmaintelligence.informa.com/products-and-services/data-and-analysis/pharmaprojects),
- and [PubMed](https://pubmed.ncbi.nlm.nih.gov/) support reviewed
- drug-target, mechanism, and primary-literature context when the agent records
- specific source-backed findings.
- ## How It Works
- Genomi exposes a small base MCP surface plus a dispatcher for specialized
- genomics tools. The host agent does the conversation; Genomi does the grounded
- lookup, Active Genome Index creation, evidence retrieval, and report assembly.
- 1. Connect an agent over MCP — see [the install steps](#or-if-you-prefer-the-old-school-way)
- above for the config snippet.
- 2. Give the agent a genome file when you want personal context.
- Genomi parses the file into an Active Genome Index: a local query substrate for
- variants, zygosity, quality, depth, filters, and callability context. Public-only
- questions do not require a genome file.
- ```json
- {
- "tool": "genomi.parse_source",
- "params": {
- "source": "<genome-file>"
- }
- }
- ```
- 3. Ask questions. The agent calls the smallest useful Genomi operation.
- Base operations such as `genomi.parse_source`, `genomi.describe_context`, and
- `journal.append_entry` are direct MCP tools. Capability operations go through
- `genomi.invoke` after the agent reads the matching `skills/<capability>/SKILL.md`.
- ```json
- {
- "tool": "genomi.invoke",
- "params": {
- "tool": "variant.resolve",
- "params": {
- "rsid": "rs429358"
- }
- }
- }
- ```
- 4. Inspect evidence, defaults, and limitations.
- Genomi results include structured evidence, source coverage, and
- `defaults_applied` where assumptions matter. Missing libraries, unavailable
- external sources, and background jobs return explicit statuses instead of being
- treated as negative evidence.
- 5. Remember.
- The Journal records observations, decisions, unresolved questions, and evidence
- links.
- ## Build With Genomi
- Genomi is open source and built for people who want AI agents to work with
- genomics responsibly: local-first, evidence-grounded, and honest about
- limitations. Use it to explore, explain, remember, and report on DNA questions
- without uploading the raw genome file.
- ## Status
- > [!WARNING]
- > **Experimental. Research and informational use only.**
- > Genomi is not a diagnostic device. It does not replace qualified clinical
- > review for diagnosis or treatment. Raw genome data stays on your machine
- > by design — but you are still responsible for how you share what comes out
- > of it.
- The schema, tool surface, and capability layout are still moving — pin a
- commit if you need stability across upgrades.
- ## License
- Genomi is released under the [Apache License 2.0](LICENSE).
- ## Citation
- If you use Genomi in research, publications, reports, benchmarks, demos, or
- derived tools, please cite the project using [CITATION.cff](CITATION.cff) and
- acknowledge Genomi where appropriate.
- ```bibtex
- @software{genomi2026,
- title = {Genomi: A Local Genomics Harness for AI Agents},
- author = {Zeng, Mingde and Zhou, Hongjian and Liu, Fenglin and Wu, Jinge},
- year = {2026},
- url = {https://www.genomiagent.com/},
- version = {0.1.0}
- }
- ```
- ## Contributing
- Issues and pull requests welcome. If you are reporting a bug, include the
- genome source format (VCF / gVCF / 23andMe / AncestryDNA / etc.), the
- operation you ran, and the structured error envelope the agent received —
- that is usually enough to reproduce.
- ## Acknowledgements
- Genomi owes a direct implementation debt to the
- [Personal Genome Project — Harvard Medical School](https://my.pgp-hms.org/public_genetic_data)
- public genetic data catalog.
- That same PGP-HMS public dataset also did the unglamorous work of letting
- Genomi support these provider shapes natively. Detectors, column quirks,
- header banners, archive wrappers, and provider-tagged VCF paths are
- sanity-checked against real PGP participant exports when the public catalog
- contains that format. Native 23andMe, AncestryDNA, MyHeritage,
- FamilyTreeDNA, Nebula, Dante, Sequencing.com, VCF, gVCF, BAM, and FASTQ
- coverage benefits directly from those examples; Living DNA and `.genome`
- remain supported formats, but the checked PGP-HMS public inventory did not
- include examples for those shapes.
- Thanks also to [GBrain](https://github.com/garrytan/gbrain), Garry Tan's
- OpenClaw/Hermes agent-brain project, for inspiration around making agent
- systems source-grounded, memory-aware, and useful from a single fetched
- documentation entry point.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.