Custom agents

Nothing about Research Scan assumes Claude Code. The interface is a run directory of JSON and a CLI with stable exit codes, so any harness that can run a subprocess and read a file can drive the pipeline — including fifty lines of Python.

There are two ways in.

Option 1 — speak MCP

If your harness already speaks MCP, launch research-scan mcp over stdio and use the four tools. You supply the judgement at each decision point; the adapter drives the CLI and manages the run directory for you.

This is the lower-effort route, and it is the one to prefer if MCP is available to you.

Option 2 — drive the CLI directly

The stages are ordinary commands. Your harness runs them in order and writes the three agent-owned files between them.

research-scan init "your question" --profile quick --json
# → write queries.json
research-scan retrieve --json
# → score every batch in screen-batches/, write screen.json
research-scan expand --json
# → score the expansion batches, append to screen.json
research-scan coverage --json
# → optionally: write round-2 queries, then
#   research-scan retrieve --round 2 && research-scan expand --round 2
research-scan shortlist --json
# → write ranked.json
research-scan verify --json
research-scan emit --json

Every stage takes --json for machine-readable stdout and --quiet to silence the stderr log. Exit codes are stable: 0 success, 2 a validation or usage failure with every offending path listed, 3 a mandatory readiness check failed.

What your harness must write

Do not write anything else. The CLI owns candidates.json, shortlist.json, manifest.json and evidence.*, and the two halves never edit each other’s files.

Get the contracts

schema.py in the package is the source of truth, and it will print itself:

research-scan schema --name Queries        # one model, as JSON Schema
research-scan schema --md                  # every model, as Markdown

Validate against those rather than against examples. Unknown keys are rejected everywhere, so a field your harness invents will surface as an exit-2 error rather than being ignored.

Bring the rubrics with you

The judgement your harness supplies should be made against the same rubrics the skill uses, or against rubrics you have deliberately changed. They ship as plain Markdown in the main repo under skills/research-scan/references/:

SKILL.md itself is the procedure: the stage order, what to do at each decision point, and the rules that hold throughout. Reading it is the fastest way to understand what a correct harness does.

The two rules it opens with are the ones to carry into any implementation:

Never cite a paper that is not in the run’s files; never edit paper metadata from memory.

Worth knowing before you build

Screening dominates. It is the agent reading the pool, and it is most of both the wall clock and the token cost. Batch it, and expect roughly 3.8 seconds per candidate at frontier-model speeds.

Do not show the screener citation counts or venues. The rubric withholds them deliberately; a harness that helpfully adds them changes what the scale means.

Abstracts are truncated to 600 characters for screening. That is the input the scale was calibrated against.

A second round adds, never subtracts. If you implement the gap round, round one’s scores stay.

Re-runs should be byte-identical. The engine’s clocks are injectable so that this holds. If your harness injects a timestamp into a file it writes, you lose the ability to diff two runs — which is the main way you will evaluate your own changes.

Related

• Artifacts and schemas — the run directory in detail.
• The agent layer — what each rubric says.
• File formats — every file, in order.