How to contribute to DisMech

Ways to Contribute

You do not need to write code or edit YAML to help. Issues are welcome from anyone, and subject-matter experts are especially encouraged to tell us what is wrong or missing.

How Curation Works Here

DisMech currently runs in a heavily agent-forward mode. We call the human role "regulating the loop" rather than being "in the loop": people direct agents and curate the process, while agents make the vast majority of edits.

• DisMech is alpha-stage and experimental. AI may make mistakes.
• Agent work is started by people or by GitHub Actions. Let agents do the work, including writing issue and pull-request comments, without editorializing.
• Assume content is AI-generated. The default assumption for any issue or PR, including its comments, is that it was written by an agent. You are not held accountable for checking everything your agent produces. If you write something yourself and want it identified as such, you may add a marker such as [human authored], but this is not required.
• YAML files are the source of truth. Every disorder is one file in kb/disorders/; the web pages are generated from them.

Be bold, and trust the process

Every member of the DisMech team is encouraged to do work that ends in a pull request. You are not expected to check the results yourself. Every PR is reviewed by agents using rubrics developed by agents and people together, and a battery of validation and anti-hallucination checks runs on every change. This is not guaranteed to be perfect, but no entry is ever considered finished: all entries are continuously refined.

Deliberately pushing an agent to add bad content is welcome as an experiment, but coordinate on Slack first (see the Bixonimania request for an example). See also issue #4794 on the use of agentic AI in this project.

Use top-tier models

Use best-in-class models and up-to-date harnesses. Weaker models produce lower-quality content; the AI reviewer, which always uses a top-tier model, will usually catch it, but the back-and-forth wastes your time. Experienced users may try other models deliberately, matched to the difficulty of the task, after coordinating on Slack.

Access & Pull Requests

Open pull requests from the main repository, not a fork

The repository depends on automated AI review, and GitHub does not give workflows started from forks access to the repository's secrets. Pull requests from forks are therefore closed automatically. Push your branch to monarch-initiative/dismech itself and open the PR from there.

If you do not have access yet, open an issue asking to be added. Known members of the Monarch and biomedical informatics communities are added promptly; others are welcome to join a community call and introduce themselves first.

Draft status does not hold a PR back

Any pull request you open is in the review queue, draft or not. Agents will review it and may push changes to move it toward merging, and the merge automation marks an otherwise-ready draft as ready before merging it. If you do not want that, push your branch without opening a PR.

When a PR merges, and how to stop it

An automated sweep merges any pull request that is approved by the reviewer, passing all checks, free of conflicts, targeting main, more than 3 days old, and not assigned to a person. To keep a PR from merging, assign it to yourself (and answer the inactivity reminders, or the assignment is released after two weeks) or leave a "changes requested" review.

Curate on Claude Code on the Web

The simplest way to curate is Claude Code on the web. The repository is cloned for you, and when you are done you press Create PR. You need a Claude Pro, Max, Team, or Enterprise plan; the free plan does not include Claude Code.

1. Connect claude.ai to GitHub

1. Go to claude.ai/code. Click the grayed-out tab near the top left that says "</> Code".

   

2. Ignore the "Download for macOS" button and click "Continue on web →" lower down.

   

3. Click "Get Started", then on the next screen click "Connect a different way".

   

4. Click "Continue with GitHub", then "Authorize".

   

5. Back at claude.ai/code, click "+ Select repo" above the message box and choose monarch-initiative/dismech. If it is not in the list, search for it.

   

2. Set up a cloud environment (once)

An environment is a saved configuration of network access, environment variables, and a setup script that your cloud sessions run in. This is the only non-obvious part, and you only do it once.

1. At claude.ai/code, click the button with a cloud icon (it probably says "Default") to open the environment selector.

   

   Hover over the environment to make the gear icon appear, and click it to open the settings dialog. (Or choose "Add cloud environment" to make a new one.)

   

2. Name the environment, for example dismech.
3. Set Network access to Full. The default, Trusted, allows only package registries, GitHub, and a few other listed domains, which blocks the literature and data sources curation uses (PubMed, ClinicalTrials.gov, Edison, OpenScientist, Orphanet, ClinGen).
4. Add your deep-research API keys under Environment variables, one KEY=value per line:

   EDISON_API_KEY=<YOUR_EDISON_KEY>
   OPENSCIENTIST_API_KEY=<YOUR_OPENSCIENTIST_KEY>

   See Deep Research for how to get them. Quotes are not needed. This field is plain text: anyone who can open the environment's settings can read the values, which on a personal account means only you.
5. Install just in the setup script. Put this single line in the Setup script box:

   uv tool install rust-just

   Without it, every session has to install just before curation can start. The setup script is also where any other one-time installs belong.

Once the environment exists, curation on the web works the same as on your own computer: /curate a disorder (or /claim-disease to pick one from the queue), then press Create PR when ready.

Tips for cloud sessions

• Keep each session focused. Each session runs in a fresh virtual machine with roughly 16 GB of memory and 30 GB of disk. One disorder, or a small group of related ones, fits easily; a session that keeps going across many unrelated diseases piles up context and downloaded files and can slow down or run out of room. Start a new session per disorder or small batch — the environment is reused automatically.
• Archive finished sessions. Archived sessions use no tokens and can be restarted. To find them, filter the sidebar session list for archived sessions.

Curate Locally

If you prefer working in a terminal, or use Codex, set up the repository on your own computer.

1. Install Claude Code. You need a Claude Pro, Max, Team, Enterprise, or Console account. The recommended installer on macOS, Linux, and WSL is:

   curl -fsSL https://claude.ai/install.sh | bash

   or with Homebrew, brew install --cask claude-code. See the setup guide for Windows and other options.
2. Install uv and just. uv manages the Python environment; just runs the project's commands. Check with just --version; on macOS, brew install uv just installs both. (Or ask your agent to do this.)
3. Clone the repository and install its dependencies:

   git clone https://github.com/monarch-initiative/dismech.git
   cd dismech
   just install

4. Set up a deep-research provider (see below) by exporting its API key in your shell profile.
5. Start Claude Code in the repository with claude, and ask:

   Give me a tour of the dismech project

   Then start curating. To pick an unclaimed disease from the curation queue and claim it so nobody else takes it:

   /claim-disease

   Or to curate a specific disorder, new or existing:

   /curate Parkinson Disease

For more on AI-assisted curation workflows in general, see ai4curation/aidocs.

Ontology databases

Most ontologies (MONDO, HP, GO, CL, CHEBI, UBERON, NCIT, NCBITaxon and others) are looked up through the EBI Ontology Lookup Service, so validation does not download them. A few (HGNC, GENO, ECTO, XCO, ICD-10-CM, ICD-11, OPL) still use local SQLite databases, downloaded on demand. Single-file commands such as just validate and just validate-terms rely on the committed term caches and only look up terms that are not cached yet. To fetch the local databases ahead of time, with resume and retry:

just fetch-ontology-dbs              # every sqlite database in conf/oak_config.yaml
just fetch-ontology-dbs hgnc geno    # only the ones you need

Deep Research

Every new disorder entry starts from a committed deep-research report: a literature review written by a research agent, saved under research/, and used by the curating agent as a source of leads. The /curate command uses Edison (falcon) unless you name another provider, for example /curate Cholera using openscientist.

Biomni dataset analysis (advanced, opt-in)

Biomni is installed with the development environment but disabled by default, because it runs model-generated code on your machine and may set up a biomedical data lake of roughly 14 GiB. Enable it only for a deliberate session with export DISMECH_ENABLE_BIOMNI=1, and also set the API key for the model provider Biomni uses (for example OPENAI_API_KEY or ANTHROPIC_API_KEY). The lake goes in $BIOMNI_DATA_PATH, or ~/.biomni-lake if that is unset. Keep the lake, raw or controlled data, and credentials out of Git, and never run uv run deep-research-client directly: that skips both this policy and the repository's reference checks. Turn it off again with unset DISMECH_ENABLE_BIOMNI.

After You Open a Pull Request

1. Validation runs. Schema checks, ontology-term checks (catching invented or mismatched term IDs), and reference checks (confirming every quoted snippet appears in its cited source) run on your changes.
2. An AI reviewer reviews it, usually within minutes, and marks it "changes requested" or approved. The rubric it applies is the dismech-pr-review skill.
3. Your agent addresses the findings. Ask it to read the review and fix everything in one push: each push drops the existing approval and starts a new review round. If you disagree with a finding, say why in a PR comment; if it cannot be resolved, assign a maintainer.
4. The PR merges automatically once it meets the conditions above.
5. The site regenerates. A GitHub workflow rebuilds the disorder pages and browser data after merge; you do not need to run anything.

Checking your work before the PR

Your agent runs these for you, and the PR will not merge until they pass. They are listed here so you know what they are:

# fast checks while curating a single entry
just validate kb/disorders/YourFile.yaml
just validate-terms kb/disorders/YourFile.yaml
just count-verified-snippets kb/disorders/YourFile.yaml

# the batched schema + terms + references check CI runs, before opening the PR
just validate-disorders kb/disorders/YourFile.yaml

# everything (slow)
just qc

Working with the Agents

Several agents run in the repository's issues and pull requests. The automation and agents guide describes them in full; the essentials are below.

Assigning an issue means "claimed"

DisMech's own agents are started by a mention, never by assignment. Assigning an issue tells the curation scanner a person has it, which takes it out of the scanner's queue. (GitHub's separate "Assign agent to issue" feature is different: there, assignment does start an agent.) To claim a disease you intend to curate, use /claim-disease, which opens a claim-labelled issue assigned to you.

Effort labels

Curation issues carry an effort label — low_effort, medium_effort, high_effort, or very-hard — and the curation scanner picks a model tier from it, with cheaper models for low-effort tasks. The mapping lives in .github/agent-config.yaml.

Getting Help

Members of the DisMech team can also ask on Slack. And you can always ask your agent: it reads the repository's current instructions, which this page may lag behind.