ADPKD Research Intelligence System

A personal, self-hosted research-tracking system for Autosomal Dominant Polycystic Kidney Disease (ADPKD). It continuously monitors the scientific literature and clinical-trial landscape, scores new findings for evidence quality and relevance, synthesizes them into living knowledge-base documents, and serves everything through a local web dashboard.

The system runs locally (built for a Mac Mini), uses Claude Code for autonomous research and synthesis, stores structured data as local JSON, and optionally syncs synthesized output to Google Drive.

Note: This is a personal research tool, not medical advice. Findings are automatically summarized and may contain errors — always verify against primary sources and consult a qualified clinician.

---

How it works

Two scheduled agents (macOS launchd) drive the pipeline:

Agent	Schedule	Purpose
com.adpkd.scan	Every 2–3 days	Light, fast sweep for new papers and trial updates
com.adpkd.deep	Weekly (Sunday)	Comprehensive synthesis and digest generation

Each agent invokes Claude Code with a mode-specific prompt. A typical run:

1. Fetches papers from Semantic Scholar / PubMed and checks ClinicalTrials.gov for updates
2. Assesses relevance and novelty against the existing knowledge base
3. Scores evidence using a dedicated evaluation framework (study design, sample size, limitations)
4. Updates the structured data store (data/*.json)
5. Updates the synthesis documents and generates alerts for significant findings

launchd (scan / deep)
        │
        ▼
   Claude Code  ──► fetch → assess → score → update data → synthesize
        │
        ▼
   Data layer (data/*.json)  ──►  Output (knowledge base, digests, alerts)
        │                                     │
        ▼                                     ▼
   Next.js dashboard  ◄───── reads ─────  Google Drive sync (optional)

---

Research taxonomy

The agent tracks ADPKD research across six dimensions, each mapped to a living knowledge-base document:

1. Pharmacological treatments — V2 antagonists, PKD1 correctors, RNA therapies, repurposed drugs, gene/stem-cell therapy
2. Dietary & lifestyle — hydration, sodium/protein restriction, ketosis, exercise
3. Genetics & biomarkers — PKD1/PKD2 variants, htTKV, novel biomarkers
4. Clinical-trials pipeline — active/recruiting trials and their status
5. Disease management — imaging, blood pressure, progression staging
6. Patient community — patient-relevant developments and resources

See adpkd-research-agent-spec.md for the full design specification.

---

Repository layout

├── prompts/           # Claude Code system prompts (scan, deep, baseline) + evaluation framework
├── scripts/           # Fetchers (PubMed/Semantic Scholar), runners, launchd plists, Drive sync
├── data/              # Structured JSON store: papers, trials, findings, run-log, user-state
├── output/
│   ├── knowledge-base/  # Six living synthesis documents
│   ├── digests/         # Weekly digests (YYYY-WXX)
│   ├── alerts/          # Dated significant-finding alerts
│   └── logs/            # Per-run logs (gitignored)
└── dashboard/         # Next.js web dashboard

Data store (data/)

File	Contents
papers.json	Tracked papers with metadata, scores, and summaries
trials.json	ClinicalTrials.gov records being followed
findings.json	Scored, synthesized findings
run-log.json	History of every scan/deep run
user-state.json	Dashboard read/seen state

---

Dashboard

A Next.js 16 + React 19 app (Tailwind CSS 4, shadcn/ui, Recharts) that reads directly from data/ and output/. Pages: overview, papers, trials, digests, and knowledge base.

cd dashboard
npm install
npm run build
npm run start   # serves on http://localhost:3000

Always run the dashboard in production mode (build + start). Dev mode (Turbopack) has been observed to spawn runaway node processes.

---

Setup

Prerequisites

• macOS (uses launchd for scheduling)
• Claude Code
• Python 3 and Node.js
• (Optional) A Semantic Scholar API key for higher rate limits

1. API keys

Create data/.api-keys.json (gitignored — never commit real keys):

{
  "semantic_scholar": "YOUR_KEY_HERE",
  "ncbi": ""
}

2. Paths

The prompts, scripts, and launchd plists in this repo use absolute paths for one machine. Update them to your own project location before running.

3. Baseline

Run the baseline fetch/process to build the initial corpus:

python3 scripts/baseline_fetch.py
python3 scripts/baseline_process.py

4. Schedule the agents

Copy the plists to ~/Library/LaunchAgents/ and load them:

cp scripts/com.adpkd.scan.plist ~/Library/LaunchAgents/
cp scripts/com.adpkd.deep.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.adpkd.scan.plist
launchctl load ~/Library/LaunchAgents/com.adpkd.deep.plist

---

Customize it for another disease

This repo is one instance of a reusable research-intelligence template — the same system also runs for primary lymphedema at lymphedema-research-intelligence. To point it at a different disease or research domain:

1. Scope & disease name — update the disease name and the in/out-of-scope definition throughout prompts/scan.md, prompts/deep.md, and .claude/CLAUDE.md. The scope gate lives in scripts/baseline_process.py (classify_* functions) — adjust its keywords.
2. Research taxonomy — redefine the six dimensions and their keyword maps (DIMENSION_KEYWORDS / SUBTOPIC_KEYWORDS in scripts/baseline_process.py) and rename the six documents in output/knowledge-base/.
3. Search queries — change the PubMed / Semantic Scholar / ClinicalTrials.gov query terms in scripts/baseline_fetch.py and scripts/pubmed_fetch.py.
4. Evaluation framework — the evidence-scoring model in prompts/evaluation-framework.md is disease-agnostic, but the skepticism flags are domain-specific — edit them to match your field's common biases.
5. Paths & schedule — update absolute paths and the launchd plist labels/times (com.<disease>.scan, com.<disease>.deep) in scripts/.
6. Dashboard — change the title, port, and palette in dashboard/ (this instance uses port 3000 and a blue theme; the lymphedema instance uses 3001 and green).

The pipeline, dashboard, scoring model, and data store are all reusable as-is — only the domain-specific configuration above needs to change.

---

License

The original source code and repository-authored documentation in this project are licensed under the MIT License.

Research publications, abstracts, article metadata, clinical-trial records, datasets, APIs, and linked services are third-party material. They are not relicensed by this repository and remain subject to their respective copyright, database rights, terms of service, and licenses. Check the source terms before copying or redistributing them.

This is a personal research tool shared for reference. Its automatically generated summaries and findings may contain errors, are not medical advice, and are provided without any warranty. Verify claims against primary sources and consult a qualified clinician before making health decisions.