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:
- Discovery — searches across Consensus (200M+ papers), Semantic Scholar, arXiv, PubMed, bioRxiv, IEEE, Springer, and 20+ other sources in parallel.
- Triage — decides per-paper whether the abstract/TLDR is enough, or whether full text is needed.
- 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.
- Extraction — Docling converts PDFs into structured Markdown with figures, tables, equations, and references preserved.
- 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).
- 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
thedotmack
Lucklyric
anthropics