Research Scan

[Research Scan logo]

research-scan

Research Scan finds and ranks recent scientific papers that matter most for a specific research question, project, or decision. Starting from a brief or a single question, it retrieves the literature, expands through citation graphs, measures coverage, verifies every DOI against the live record, and emits evidence objects — while the agent driving it plans the queries, screens the candidates and ranks the shortlist. It is an evidence pipeline for a reasoning agent, not an assistant that answers questions.

Documentation: https://researchscan.synectic.org

The work is split in two, deliberately.

The CLI is deterministic and model-free. It retrieves across OpenAlex, Semantic Scholar and arXiv, walks the citation graph, dedups, counts coverage per criterion, shortlists, verifies every DOI against the live record, applies the selection rules and renders the result. It contains no LLM SDK and makes no judgement about a paper.

The agent supplies the cognition. Planning the queries, scoring each candidate 0–3, writing gap queries when coverage is thin, and reranking the shortlist are all model decisions. The skill packages the rubrics they are made against, as plain Markdown in skills/research-scan/references/; whatever agent hosts it executes them.

Files are the interface between the two halves: the filesystem is the protocol boundary between reasoning and execution, not a storage detail. That is what lets Claude Code, Codex, Cursor or a plain Python loop drive the same chain over the same artifacts.

brief ─▶ [plan queries] ─▶ retrieve ─▶ [screen 0–3] ─▶ expand ─▶ [screen] ─▶ coverage      ─▶ [gap round, if coverage is thin] ─▶ shortlist ─▶ [rerank] ─▶ verify ─▶ emit

Bracketed steps are the agent's; the rest are CLI stages.

Two things bound the result. A purpose — build, research or orient — decides what a paper has to do to earn a slot. A profile — quick, standard or deep — decides how much the scan costs. Both are described under How it works.

Output is a run directory of validated JSON plus a Markdown brief you can hand to a human, in which every paper's DOI, title, year and first author were checked against the live record.

Install

Python ≥ 3.11 and uv.

uvx research-scan doctor          # run any command without installinguv tool install research-scan     # or put it on PATH permanently

Configure

configure asks for each credential, shows what is already set, writes ~/.config/research-scan/.env with mode 0600 inside a 0700 directory, and finishes by running doctor.

research-scan configure          # `setup` is an alias for the same command

Keys are read without echo. Re-running is safe: every variable shows its current value masked to the last four characters, Enter keeps it, typing replaces it. Anything already in the file that configure does not ask about — comments included — is left exactly as it was. If stdin is not a terminal it prints the file to write and exits 2 rather than hanging, which is the behaviour you want in a Dockerfile or a provisioning script.

To write the file by hand instead, .env.example in the repo is the template. Process environment beats ~/.config/research-scan/.env, which beats a repo-local ./.env.

Check it works

doctor invokes every source live with the cache bypassed, rather than listing what it thinks is configured.

research-scan doctor             # a four-line summary and a verdictresearch-scan doctor --verbose   # every check, with timings and pathsresearch-scan doctor --json      # machine-readable; this is the CI/agent interface

Research Scan <version>✓ configuration✓ OpenAlex   ✓ Semantic Scholar   ✓ Crossref   ✓ arXiv   ○ PubMed  PubMed: endpoint reachable; source routed for biomed but not built✓ writable run storeReady.

Exit 0 means go. Exit 3 means a mandatory check failed; see Troubleshooting. The checks and the exit code are identical in all three output modes — only the presentation differs.

○ marks a source that is routed but has no retrieval adapter — see the sources table. The probe still runs and still reports honestly: PubMed's row says the E-utilities endpoint answered, which is a different claim from being able to retrieve from it. doctor --json carries the same fact as sources_not_built, alongside a providers map whose keys and values are unchanged.

Your first scan

With the skill installed, ask for a scan in your agent:

/research-scan "I am designing a financial education product for young adults. Research question: What interventions have the strongest recent evidence for increasing long-term savings behavior?
Context:- I am interested in mechanisms that change real-world behavior, not just financial literacy scores.- Prioritize randomized trials, large field studies, and strong causal evidence.- Include evidence that challenges the assumption that education alone works.
Find the 10 papers that should shape our product decisions. Explain why each paper matters, what it found, and what evidence gaps remain." --profile standard

A one-line question works. A brief with context works better, because the planning step maps each section of it onto a specific part of the search plan. The template is skills/research-scan/examples/brief.example.md — a worked build brief — and brief.research-example.md is the same template at Purpose: research.

/research-scan research/my-brief.md --profile standard --top 10

Results land in research/scans/<YYYY-MM-DD>-<slug>/. See Outputs.

Full argument list:

/research-scan <brief.md | "question"> [--profile quick|standard|deep] [--top N] [--foundational N]                                       [--from YYYY-MM] [--to YYYY-MM] [--slug name]                                       [--domain behavioral|cs|biomed|general]                                       [--max-candidates N] [--per-query N] [--gap-round]

Connect your agent

Two front doors to the same pipeline. The skill is where the rubrics live, so it is the one that carries the screening and reranking cognition; the MCP server exposes the same four decision points as tools for any client that speaks MCP.

Claude Code — the skill

Any one of these; all three point at the same skills/research-scan/.

# 1. symlink a clone — edits to the rubrics take effect immediatelyln -s "$PWD/skills/research-scan" ~/.claude/skills/research-scan
# 2. load the repo as a plugin, per invocation (it carries .claude-plugin/plugin.json)claude --plugin-dir /path/to/research-scan
# 3. skills CLInpx skills add Synectic-Research/research-scan

Codex and other Agent Skills hosts

The skill follows the open Agent Skills format, so the same folder serves Codex, Cursor, Copilot and any other host that reads SKILL.md. Codex looks in ~/.agents/skills:

mkdir -p ~/.agents/skills && ln -s "$PWD/skills/research-scan" ~/.agents/skills/research-scan

The CLI needs the network, which Codex's default sandbox blocks. Run research-scan doctor once outside Codex (it creates the cache and config directories), then start a scanning session with network access and the cache writable. Both apply to the whole session, not only to research-scan. A full scan is a long, unattended task, so run it with codex exec and say that it should finish:

codex exec --sandbox workspace-write -c sandbox_workspace_write.network_access=true \  --add-dir ~/.cache/research-scan \  'Use the research-scan skill on brief.md with --profile quick, and run every step through the report.'

Outside a git repository, codex exec also needs --skip-git-repo-check.

Claude Code — the plugin

The plugin installs the skill and configures the uvx MCP server in one step; the .mcp.json route below stays the path for non-plugin clients such as Claude Desktop and Cursor.

/plugin marketplace add Synectic-Research/research-scan/plugin install research-scan@synectic

Any MCP client — stdio

research-scan mcp speaks MCP on stdin/stdout and nothing else. It reads no token and needs none: the process is trusted because your client launched it. Nothing extra to install — the server ships with the package.

{  "mcpServers": {    "research-scan": {      "command": "uvx",      "args": ["research-scan", "mcp"]    }  }}

Four tools, one per model decision the pipeline needs: scan_start (you supply the query plan), scan_continue (screening scores, gap queries, or a page of rerank entries), scan_verify and scan_result. They are not a chat endpoint over the pipeline: each is a decision point where a judgement is needed, and the client's model supplies exactly the cognition the skill would — same stage order, same artifacts. The adapter drives the CLI as a subprocess and reads its exit codes. Run research-scan mcp --help for the other transport.

How it works

Each stage is idempotent and re-runnable: change queries.json or pass a flag and re-run from the stage it affects. The CLI owns candidates.json, shortlist.json, manifest.json and evidence.*; the agent owns queries.json, screen.json and ranked.json. Neither edits the other's files.

Purpose

Declared on the brief's Purpose: line, or inferred. It decides which sub-criteria the plan derives, what screening counts as relevant, and what why_it_matters has to argue.

Profiles

One flag sets how much the scan costs. --profile belongs to init and is recorded in the manifest; an explicit flag still overrides it — --per-query 60 means 60 whatever the profile says.

The out-of-window total is a budget for the whole run, not a per-stage allowance. Start at standard; use quick for "what is out there" and deep when a miss is expensive. Measured recall for each is under Measured results.

The gap round

Runs at most once, and on standard only when coverage reports that the criteria are unevenly covered or that a query came back nearly empty — otherwise it is skipped and the report says so. coverage counts, per sub-criterion, how many papers screening kept; the agent writes one or two queries against the criteria that came back thinnest; retrieve --round 2 and expand --round 2 add what they find. Round 1's papers and their scores are never discarded — the pool only grows.

Supported sources

--domain picks the routing: behavioral and general → OpenAlex + Semantic Scholar; cs → those plus arXiv; biomed → those plus PubMed. --sources overrides the map outright.

Measured results

Two curated golden topics — behavioural economics and LLM literature-search agents — scored at the candidates stage and by an independent judge model. These are two topics, not a benchmark against other tools.

Judged precision of the in-window top 10: 0.875 on both topics, by an independent judge.

Recall climbs with the pool and efficiency falls with it: quick returns 0.199 recall per 100 candidates screened on topic 1 where deep returns 0.157. What separates the profiles most is the out-of-window budget (12 / 20 / 30) — topic 1's remaining misses are all pre-window classics, and each step up admits one more.

Full tables, what was tried and reverted, and the rules the numbers obey: docs/measurements.md.

Outputs

Everything lands in research/scans/<YYYY-MM-DD>-<slug>/:

A paper whose DOI did not resolve, or whose title, year or first author disagreed with the live record, is flagged, not silently repaired: it ships with mismatches[] and an [UNVERIFIED — check manually] marker. Only retraction removes a paper.

Print any data contract with research-scan schema --name <Model>, or all of them as Markdown with research-scan schema --md.

Cost and time

Wall clock tracks the candidate pool, because screening is the long pole. Measured end to end (counts.wall_clock_s, init → emit):

OpenAlex bills ≈ $0.008 either way — per_page is free depth, so pool size costs almost nothing in API money.

Agent tokens are the real cost, and they do not fall as fast as the pool does: the 120-candidate run still cost ≈ $5.70 in frontier-model tokens and ran only 3 minutes quicker than the 250-candidate one, because reranking (52 full records, regardless of pool size) and fixed stage overhead dominate once screening is small. --max-candidates is the right dial for a runaway cs pool, not a way to make a scan cheap.

The default cap scales with the number of built sources (450 × n/2, so 675 for cs, 450 for two). --max-candidates and --per-query belong to retrieve and override it per run. Both are run flags, not config.

Headless

The skill returns a ScanSummary, so a scan can run unattended and hand structured JSON to whatever comes next:

claude -p "Use the research-scan skill to scan brief.md with --slug nightly --top 5. \           When it finishes, return its ScanSummary as your final answer." \  --plugin-dir /path/to/research-scan \  --allowedTools "Bash(research-scan *),Read,Write,Edit,Glob,Grep" \  --output-format json \  --json-schema "$(research-scan schema --name ScanSummary)" \  > scan.json
jq '.structured_output.counts' scan.json

Ask for the skill in prose; do not use a bare /research-scan … slash command here. The skill declares context: fork, so a bare slash command runs entirely inside the fork and the session returns num_turns: 0 with result: "Command completed" — the scan succeeds and writes its run directory, but there is no top-level assistant turn for --json-schema to bind to and structured_output comes back null. Phrasing it as an instruction makes the session invoke the skill, receive the fork's report and emit the ScanSummary itself, which is what the schema attaches to. Verified both ways on 2026-08-19.

Two more flags to get right:

• --plugin-dir is unnecessary if the skill is already installed under ~/.claude/skills/. Never combine it with --bare: bare mode skips --plugin-dir, so the skill would not load at all.
• --allowedTools must carry Bash(research-scan *), Read, Write, Edit, Glob and Grep: the skill's own allowed-tools line, minus the four scan_* MCP tools a headless run does not use.

Not for

Systematic reviews. There is no PRISMA trail and no workflow for screening thousands of records.

Manuscript citation management. evidence.bib is a courtesy, not a library. Use a citation manager.

Full-text work. Retrieval and screening run on titles, abstracts and metadata. No PDF is fetched, parsed or read.

Google Scholar, Scopus, Web of Science, PsycInfo are not sources and are not planned: none offers a personal-key API or a ToS-compatible path.

Troubleshooting

doctor exits 3. A mandatory check failed — read the check name and fix that, rather than working around it. A missing OPENALEX_API_KEY is a FAIL, and the OpenAlex probes are then reported as SKIP rather than as passing, because they were never run. A missing S2_API_KEY or NCBI_API_KEY is only a WARN: the scan still runs, throttled. The default output names what to do; --verbose gives the full check list with timings, and --sources openalex,s2 narrows what is checked.

Reading doctor from a script or an agent. doctor --json is the interface, and its keys are stable. ready is the boolean, providers maps each checked source to ok / warn / fail / skip — skip meaning the probe never ran, which is never the same as passing — and checks carries every individual result. The exit code is the same in all three output modes.

arxiv HTTP 429, cs/physics routing skipped. arXiv rate-limits aggressively (the client already holds to 1 request / 3 s) and returns 429 under load. This is a WARN, not a failure: cs scans fall back to OpenAlex + Semantic Scholar, which carry arXiv preprints anyway — you lose the same-day listings and one origin signal, not coverage. Re-run later if recency matters; per-source query counts and failures are in manifest.json under retrieval.per_source.

Semantic Scholar backlog. S2 answers 429/503 when its queue is deep. http.py retries and then returns the last response rather than raising — a bad status is data. Graph expansion falls back to OpenAlex's bare-id reference list, which works but cannot be ranked (ordering it would cost a metadata fetch per reference), so expansion recall drops. expansion.log.jsonl records it per call.

A stage exits 2. An agent-written file failed validation. The error lists every offending path; unknown keys are rejected everywhere, so a typo surfaces instead of being swallowed. Fix the file and re-run that stage.

research-scan mcp cannot import the server. fastmcp is a core dependency, so this means an incomplete install rather than a missing option — reinstall with uv tool install research-scan. research-scan version --json reports "mcp": "enabled" on an intact install.

Shell completion

eval "$(research-scan completion bash)"   # add to ~/.bashrceval "$(research-scan completion zsh)"    # add to ~/.zshrcresearch-scan completion fish > ~/.config/fish/completions/research-scan.fish

Development

git clone https://github.com/Synectic-Research/research-scancd research-scanuv syncuv run ruff check && uv run pytest -q     # the before-commit gateuv run pytest -m live                     # the only tests that touch the networkuv tool install --editable .              # put research-scan on PATH, tracking the working tree

src/research_scan/schema.py is the source of truth: it generates the JSON Schema, the contract docs the agent reads (skills/research-scan/references/schemas.md — regenerate it in the same commit, a test compares them), and the exit-2 error messages.

AGENTS.md holds the operating doctrine, docs/measurements.md the measured results behind the current defaults, and eval/ the golden-set harness (research-scan eval --topic <t> --run <dir>).

drivers/ holds experimental reference implementations of a cognition engine — code that produces the judgements a scan needs, for people who want one driven by something other than a hosting agent. They live in the repository only: nothing there is installed by the package, imported by it, or shipped in its sdist or wheel, and no engine protocol ships in this release.

Documentation · CONTRIBUTING.md · SECURITY.md · CHANGELOG.md · CODE_OF_CONDUCT.md · CITATION.cff · LICENSE (Apache-2.0)

Dependencies keep their own licenses; THIRD_PARTY_LICENSES.md says what they are and how to regenerate the table.