coscientist-deep-research

Coscientist

A personal academic-research-agent toolkit for Claude Code. Assembled Lego-style from atomic skills + existing MCP servers rather than a monolithic app.

What it does

Given a research question, an agent works through it end-to-end:

1. Discovery — searches across Consensus (200M+ papers), Semantic Scholar, arXiv, PubMed, bioRxiv, IEEE, Springer, and 20+ other sources in parallel.
2. Triage — decides per-paper whether the abstract/TLDR is enough, or whether full text is needed.
3. Acquisition — fetches PDFs through an open-access fallback chain, falling through to your institution's access via OpenAthens when OA sources don't have it.
4. Extraction — Docling converts PDFs into structured Markdown with figures, tables, equations, and references preserved.
5. Analysis — 10 specialized sub-agents (Scout, Cartographer, Chronicler, Surveyor, Synthesist, Architect, Inquisitor, Weaver, Visionary, Steward) work through the corpus with three human-in-the-loop review breaks. Phase 1 personas run in parallel (v0.51).
6. Output — produces a Research Brief + six-section Understanding Map + RUN-RECOVERY.md, with every claim traceable to its source paper in a SQLite run log. Brief now includes hypothesis cards + per-section evidence tables + Socratic discussion questions (v0.54).

Three research modes

lib/mode_selector.py picks the right mode automatically.

Mode	Use for	Cost	Time
Quick	Concrete one-shot ("summarize this", "list venues")	$0.05–0.30	30s–2m
Deep	Open-ended research question	$3–5	15–25 min
Wide	N items processed identically (10 ≤ N ≤ 250)	$5–30 (cap $50)	5–20 min

Wide → Deep handoff (v0.53.5): triage 100 papers via Wide, then seed Deep from the top-30 shortlist:

# 1. Wide-triage 100 papers
uv run python .claude/skills/wide-research/scripts/wide.py init \
  --query "..." --items items.json --type triage
# (Gate 1 approve → orchestrator dispatches sub-agents → synthesize)

# 2. Deep run, seeded from Wide
uv run python .claude/skills/deep-research/scripts/db.py init \
  --question "..." --seed-from-wide <wide-id> --seed-mode abstract

Install

Coscientist ships as a Claude Code plugin marketplace. Add the marketplace once, then install whichever components you want:

/plugin marketplace add epireve/coscientist

# Full deep-research pipeline (10-agent Expedition + skills + agents)
/plugin install coscientist-deep-research@coscientist

# Custom MCP servers (each installable independently)
/plugin install coscientist-retraction-mcp@coscientist
/plugin install coscientist-manuscript-mcp@coscientist
/plugin install coscientist-graph-query-mcp@coscientist

Plugin	What it adds
coscientist-deep-research	11 skills + 10 agents + /deep-research slash command
coscientist-retraction-mcp	MCP server for retraction status (Crossref + PubPeer). 3 tools.
coscientist-manuscript-mcp	MCP server: .docx / .tex / .md → AST. 4 tools.
coscientist-graph-query-mcp	Read-only MCP over the per-project citation graph. 6 tools.

Full server inventory + tool reference: MCP_SERVERS.md.

Coscientist also consumes several third-party MCPs (Consensus, paper-search, semantic-scholar, academic, zotero, playwright, browser-use). They're not republished here — see EXTERNAL_MCPS.md for setup.

Install troubleshooting

Symptom	Likely cause + fix
/plugin install fails with "marketplace not found"	Run /plugin marketplace add epireve/coscientist first.
MCP server doesn't appear in claude mcp list after install	Plugin's .mcp.json uses ${CLAUDE_PLUGIN_ROOT} — make sure your Claude Code version supports plugin env vars (≥ 2.0.0).
mcp package not found at runtime	Either install via uv sync --extra mcp (source tree) or rely on uv run --with mcp declared inside each plugin's .mcp.json.
pandoc not on PATH errors from manuscript-mcp	Only .docx parsing needs pandoc. Install via brew install pandoc or distro package manager. Markdown + LaTeX paths work without it.
coscientist-graph-query-mcp errors lib.graph not found	Plugin vendors its own lib/; check that plugin/coscientist-graph-query-mcp/lib/graph.py exists. The marketplace install should include it.
Want to verify everything before reporting a bug?	Run uv run python -m lib.install_check --with-mcp-list. Returns a structured JSON report on every plugin + (optionally) claude mcp list output.

Architecture

Each skill is atomic and does one job. Skills compose through a shared paper artifact on disk — no skill calls another skill directly, so any piece can be swapped out.

~/.cache/coscientist/papers/<paper_id>/
  manifest.json       metadata.json
  content.md          frontmatter.yaml
  figures/  tables/   references.json
  equations.json      raw/  extraction.log