consensus

Consensus CLI

Search Consensus.app for academic papers via the consensus CLI tool.

Binary: ~/projects/consensus-cli/consensus

Requires: Dia browser running with CDP enabled on port 9222.

Check: ls ~/projects/consensus-cli/consensus || echo "MISSING: consensus binary not built"

Core Command

consensus search "<query>" [options]

Flags

Flag	Description
--n <int>	Result count (default 20, max 100)
--type <csv>	Study types: rct,systematic,meta,non_rct,observational,lit_review,case,animal,in_vitro
--years <range>	Year range: 2018-2024 or past N years (e.g. 5)
--min-citations <int>	Minimum citation count
--rank <q1|q2|q3|q4>	Journal quartile filter (SJR)
--human	Human studies only
--rct	Shorthand for --type rct
--open-access	Open access papers only
--domain <csv>	Fields of study (e.g. Medicine,Chemistry)
--country <csv>	Country filter (e.g. USA,UK)
--page <int>	Page number (default 0)
--sort <field>	Client-side sort: citations (descending)

Output Fields (per paper)

{
  "title": "...",
  "authors": ["..."],
  "year": 2023,
  "journal": "...",
  "doi": "...",
  "citations": 150,
  "study_type": "rct",
  "takeaway": "One-sentence finding...",
  "open_access_pdf_url": "https://... or null",
  "url": "https://consensus.app/papers/..."
}

Domain Knowledge Integration

ALWAYS read the domain knowledge file before presenting results.

File: ${CLAUDE_SKILL_DIR}/../google-scholar/domain-knowledge.local.md

This file contains the user's curated list of trusted journals and authors. Use it to:

1. Mark trusted sources — ★ before papers whose journal matches a trusted journal
2. Resolve SSRN labels via DOI — when journal looks like an SSRN label, use the doi field to look up the real journal (see DOI Resolution below)
3. Filter on request — when user asks for "relevant journals only", return only ★ papers
4. Suggest refinements — use known trusted authors to suggest follow-up searches

SSRN Label Detection & DOI Resolution

SSRN label patterns (journal field is NOT the real venue):

• Contains "eJournal", "Topic)", "SSRN Electronic Journal"
• Starts with a subject code: PSN:, ERN:, ERPN:, SRPN:, POL:, LSN:

When a paper has an SSRN-label journal AND a non-null doi:

curl -s "https://api.crossref.org/works/<doi>" | uv run python3 -c "
import json, sys
d = json.load(sys.stdin)
msg = d.get('message', {})
ct = msg.get('container-title', [])
print(ct[0] if ct else 'NOT FOUND')
"

Use the resolved journal name to re-check against the trusted list. If it matches, mark ★ with a note: ★ (resolved via DOI from SSRN label).

If doi is null or CrossRef returns no container-title: leave as unresolved SSRN label.

Presentation Format

★ [Title](url) — Authors (Year), *Journal*, N citations
  > Takeaway: ...

★ [Title](url) — Authors (Year), *Resolved Journal* (resolved via DOI), N citations
  > Takeaway: ...

[Title](url) — Authors (Year), *Journal* [SSRN label, unresolved], N citations
  > Takeaway: ...

Trusted papers first (confirmed then resolved), then unresolved, then non-trusted.

IRON LAW: Always Use the CLI Binary

NEVER use mcp__consensus__search. ALWAYS use the ~/projects/consensus-cli/consensus binary. This is not negotiable.

The MCP tool is rate-limited to 3 results per search and requires a free account. The CLI binary uses the enterprise account session in Dia and returns up to 100 results with no rate limit.

Red Flags — STOP If You Catch Yourself:

Action	Why Wrong	Do Instead
Using mcp__consensus__search instead of the CLI	MCP is rate-limited to 3 results; CLI has no limit	Always use ~/projects/consensus-cli/consensus
Presenting results without reading domain-knowledge.local.md	User expects journal quality signals on every search	Read domain knowledge first, always
Treating SSRN topic labels as real journals without checking DOI	The paper may be in JF or JAE — you'd miss a trusted hit	Run CrossRef DOI lookup first
Skipping DOI resolution because there are many SSRN-labeled papers	High-citation SSRN-labeled papers are often published in top venues	Resolve all of them — it's one curl per paper
Using --rank q1 as a journal quality filter	The API maps SSRN working papers under Q1 labels — it is not reliable	Use domain-knowledge.local.md + DOI resolution instead
Passing --n > 100	CLI validates and rejects — exits non-zero	Max is 100

Decision Tree

User wants papers on a topic
    ↓
Read domain-knowledge.local.md
    ↓
Run: consensus search "<topic>" --n 50 --sort citations [filters]
    ↓
For each paper:
  journal matches trusted list? → ★
  journal is SSRN label + doi present? → curl CrossRef → re-check → ★ if match
  else → unresolved / non-trusted
    ↓
Present: ★ confirmed, ★ resolved, then rest
    ↓
User wants "only relevant journals"?
  YES → Return only ★ papers
  NO  → Return all, stars indicate quality

Common Patterns

# Basic search — sort by citations to surface highest-impact papers first
consensus search "mandatory disclosure effects" --n 50 --sort citations

# Restrict to RCTs
consensus search "aspirin cardiovascular" --rct --n 10

# Recent papers, high-citation
consensus search "ESG disclosure" --years 5 --min-citations 50

# Systematic reviews only
consensus search "minimum wage employment" --type systematic

# Combine server-side quartile hint with domain-knowledge filtering
consensus search "corporate governance" --rank q1 --n 30
# (then filter ★ from output using domain-knowledge.local.md)

Operational Notes

1. Dia browser must be running — if CDP fails, the CLI exits 1 with "Dia browser not running (CDP port 9222 unreachable)"
2. Consensus.app uses guest-mode rate limiting — avoid rapid back-to-back searches
3. --rank q1 is imprecise (SSRN papers slip through) — domain-knowledge.local.md is the reliable quality gate
4. study_type comes from Consensus badges and may be null for many papers
5. open_access_pdf_url is null when no PDF is available (not undefined)