research-helper

A Claude Code plugin for academic research workflow in CS/ML/NLP.

Status

v0.5.3 — ships lit-scan, lit-digest, experiment-design, pipeline-scaffold, and result-analyze. lit-scan also queries OpenAlex (with topic tags); both lit-scan and lit-digest support a .env file for API keys. This release brings full arXiv API conformance — broader category coverage, server-side date filtering, pagination, ToU-compliant throttling, and version-suffix preservation.

Install

This plugin uses the Claude Code marketplace format. The marketplace catalog at .claude-plugin/marketplace.json lists one plugin (research-helper) sourced from ./plugins/research-helper/.

From GitHub (recommended for end users)

In any Claude Code session, run:

/plugin marketplace add Mhburg/research-helper
/plugin install research-helper@research-helper
/reload-plugins

From a local clone (recommended for development)

Clone the repo first, then in Claude Code:

/plugin marketplace add /path/to/cloned/research-helper
/plugin install research-helper@research-helper
/reload-plugins

The path you pass to /plugin marketplace add must contain .claude-plugin/marketplace.json at its root.

Updating

After the marketplace owner publishes a new version (the version field in plugin.json), refresh and reinstall:

/plugin marketplace update research-helper
/plugin uninstall research-helper@research-helper
/plugin install research-helper@research-helper
/reload-plugins

Claude Code also auto-updates marketplaces at startup, so a fresh session typically picks up new versions without manual intervention.

Skills

lit-scan — ranked, clustered literature search

Searches Semantic Scholar + arXiv for a topic, dedupes, clusters by approach, and writes a structured reading list to ./research/<topic>-YYYY-MM-DD.md. Also queries OpenAlex by default, surfacing topic tags from OpenAlex's 4-level taxonomy. Pass --no-openalex to disable. Now also queries cs.AI / cs.IR / stat.ML with server-side submittedDate filtering and pagination support.

Triggers (model-invoked):

• "What's been done on X?"
• "What's the current SOTA for Y?"
• "Lit review on Z"

Manual invocation:

/research-helper:lit-scan transformer long-context methods

Direct script invocation (without Claude — paths relative to repo root):

python plugins/research-helper/skills/lit-scan/scripts/search.py \
  --query "QLoRA reproductions on 13B causal LMs" --since 2024 --max 40 --output results.json

NLP/LLM-tuned out of the box — knows about ACL/EMNLP/NAACL/COLM venues and weights them above generic ML venues.

Setup (optional but recommended):

PowerShell:

$env:SEMANTIC_SCHOLAR_API_KEY = "..."   # avoids the anonymous-pool rate limit
$env:OPENALEX_API_KEY = "..."           # optional; authenticated OpenAlex tier

Bash / Zsh:

export SEMANTIC_SCHOLAR_API_KEY="..."
export OPENALEX_API_KEY="..."

Or use a .env file in your working directory (see the .env support section).

lit-digest — deep-dive on a single paper

Given a specific paper (arXiv ID, DOI, URL, S2 ID, ACL Anthology, or OpenReview), produces a structured prep packet (metadata, references, citations, S2 recommendations, optional PDF text) and writes a markdown digest to ./research/digests/<slug>-YYYY-MM-DD.md. When OpenAlex resolves the paper, the JSON output now includes a topics field with OpenAlex's 4-level taxonomy. Preserves arXiv version suffixes (e.g., 2401.12345v2) through to the fetch.

Triggers (model-invoked):

• "Summarize this paper: "
• "What does build on?"
• "Critique "

Manual invocation:

/research-helper:lit-digest 2305.14314

Direct script invocation:

python plugins/research-helper/skills/lit-digest/scripts/digest.py \
  --paper "https://arxiv.org/abs/2305.14314" --pdf \
  --output research/digests/qlora-2026-05-21.json

Setup (optional but recommended):

Set SEMANTIC_SCHOLAR_API_KEY (avoids the anonymous-pool rate limit) and OPENALEX_API_KEY (enables OpenAlex fallback for S2 404s and non-arXiv PDF resolution) in your shell or a .env file. Install the optional PDF dependency:

pip install pypdf   # enables --pdf full-text extraction

experiment-design — write a structured experiment-spec before running code

Given a research question, walks you through writing a falsifiable, structured experiment spec covering hypothesis, variables, baselines, metrics, statistical test, multi-seed plan, and threats to validity. Output: research/experiments/<slug>-YYYY-MM-DD.md.

Triggers (model-invoked):

• "Design an experiment for X"
• "What should I run to test Y?"
• "Help me write an experiment plan"

Manual invocation:

/research-helper:experiment-design "Does QLoRA outperform LoRA on 13B causal LMs?"

Direct script invocation:

python plugins/research-helper/skills/experiment-design/scripts/design.py \
  --question "Does removing layer norm hurt downstream task accuracy?" \
  --type ablation

No env vars or external deps required (Python stdlib only).

pipeline-scaffold — emit a starter experiment codebase

Given a task type (classification | generation | prompt-eval) and either a slug or an experiment-design spec, drops a self-contained codebase into research/code/<slug>/ with config, data loader, model, training/inference loop, eval, multi-seed runner, and README.

Triggers (model-invoked):

• "Scaffold experiment code"
• "Set up training code for X"
• "I have a spec, now make the code"

Manual invocation:

/research-helper:pipeline-scaffold classification --slug my-experiment

Direct script invocation:

python plugins/research-helper/skills/pipeline-scaffold/scripts/scaffold.py \
  --task classification \
  --from-spec research/experiments/qlora-vs-lora-2026-05-21.md

The scaffold itself uses stdlib only. The emitted code has per-task requirements.txt (transformers/datasets/torch/etc.) the user installs after scaffolding.

result-analyze — paired statistical analysis of multi-seed results

Reads outputs/seed-*/results.json files across one or more variants (produced by pipeline-scaffold runs) and emits a markdown + JSON report at research/analysis/<slug>-YYYY-MM-DD.md covering bootstrap confidence intervals, paired t / Wilcoxon, multiple-comparisons correction, and a primary-metric callout.

Triggers (model-invoked):

• "Analyze my results"
• "Compare baseline vs treatment"
• "Run statistical tests on these experiments"
• "Is the difference significant?"

Manual invocation:

/research-helper:result-analyze

Direct script invocation:

python plugins/research-helper/skills/result-analyze/scripts/analyze.py \
  --variant baseline:'research/code/qlora-vs-lora/outputs/seed-*/results.json' \
  --variant treatment:'research/code/qlora-vs-lora-v2/outputs/seed-*/results.json' \
  --from-spec research/experiments/qlora-vs-lora-2026-05-21.md

Reproducible (--bootstrap-seed), no network calls. Pairs --correction holm (default) with bootstrap CIs to keep multi-pair comparisons honest.

Layout

research-helper/
├── .claude-plugin/marketplace.json    # marketplace catalog (one entry: research-helper)
├── README.md
├── .gitignore
└── plugins/research-helper/
    ├── .claude-plugin/plugin.json     # plugin manifest (version, author, etc.)
    └── skills/
        ├── lit-scan/
        │   ├── SKILL.md
        │   ├── scripts/
        │   └── fixtures/
        ├── lit-digest/
        │   ├── SKILL.md
        │   ├── scripts/
        │   └── fixtures/
        ├── experiment-design/
        │   ├── SKILL.md
        │   └── scripts/
        ├── pipeline-scaffold/
        │   ├── SKILL.md
        │   ├── scripts/
        │   └── templates/
        │       ├── classification/
        │       ├── generation/
        │       └── prompt-eval/
        └── result-analyze/
            ├── SKILL.md
            └── scripts/

Design specs and implementation plans live on the local branch under docs/superpowers/{specs,plans}/. They're excluded from main to keep the publishable tree focused on runtime artifacts.

Dependencies

Per-skill, in order of weight:

• lit-scan and lit-digest: requests (only required dep). Optional: pypdf for lit-digest's --pdf extraction.
• experiment-design: Python stdlib only.
• pipeline-scaffold: Python stdlib only (the scaffold itself; emitted code has its own requirements.txt).
• result-analyze: scipy>=1.11, numpy>=1.24.

Install:

pip install -r plugins/research-helper/skills/lit-scan/scripts/requirements.txt
pip install -r plugins/research-helper/skills/lit-digest/scripts/requirements.txt
pip install -r plugins/research-helper/skills/result-analyze/scripts/requirements.txt
pip install pypdf   # optional, for lit-digest --pdf

Tests run without network — lit-scan and lit-digest use fixtures in their respective fixtures/ directories; experiment-design, pipeline-scaffold, and result-analyze use only generated fixtures / pure rendering.

.env support

Both lit-scan and lit-digest look for a .env file in the current working directory (and any parent directory), and load any unset KEY=value pairs into the process environment before running. Existing environment variables always win — .env is only a fallback. This lets you keep OPENALEX_API_KEY / SEMANTIC_SCHOLAR_API_KEY scoped per project without exporting them globally. The export prefix and shell interpolation are not supported.

License

MIT