Research Scan

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 installing

uv 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 verdict

research-scan doctor --verbose # every check, with timings and paths research-scan doctor --json # machine-readable; this is the CI/agent interface

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

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/ - /. 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 immediately

ln -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 CLI

npx 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 — `-