Paper Workflow

Turn Claude Code into a research assistant. Install in one command, remove in one command. Zero residue.

中文版 README

把 Claude Code 变成论文研究助手——零侵入安装，一键拆卸。

Release Status: Alpha Python License: MIT Tests MCP

---

What it does

you: /paper-search "LLM agent reasoning 2024"

you: /paper-ingest 1,3,5

you: What attention variants exist in the literature?

Every claim is backed by a direct quote from the actual PDF — not the model's training data.

---

Why this project

• Evidence-first, not guessing. Ask a research question → get exact quotes with paper title, page number, and relevance score. Not LLM hallucinations.
• Zero CC modification. Installs through Claude Code's official extension system (Skills + MCP + Rules). Your coding workflow is untouched.
• Fully removable. install.sh writes a manifest. uninstall.sh reads it and removes exactly those files. Disable/enable in < 1 second.

---

Quick Start

Already have Claude Code?

git clone https://github.com/Minazuki02/paper-workflow.git
cd paper-workflow
bash scripts/install.sh

Then start claude from any directory — paper tools are globally available:

claude
# Try: /paper-search "transformer attention"

Toggle paper mode on/off without touching your data:

bash scripts/paper-workflow.sh disable   # pure coding mode
bash scripts/paper-workflow.sh enable    # paper tools back

Full removal: bash scripts/uninstall.sh

Requirements: Python ≥ 3.11 · Claude Code installed

Just exploring?

No Claude Code needed to browse the codebase or run backend tests:

git clone https://github.com/Minazuki02/paper-workflow.git
cd paper-workflow
pip install -e backend[dev]
pytest tests/

See Architecture → for how it works.

---

How it works

┌─────────────────────────────┐
│ Claude Code  (unmodified)   │
│  Skills · Agents · Rules    │
│         ↕ MCP (stdio)       │
├─────────────────────────────┤
│ Python Backend (this repo)  │
│  Ingest → Retrieve → Analyze│
│  SQLite + FAISS + PDF store │
└─────────────────────────────┘

CC stays the orchestrator. The backend does all heavy lifting (PDF parsing, embedding, retrieval) through MCP.

Design principles:

• CC doesn't touch data. Backend doesn't touch users. MCP bridges the two.
• Everything injected into ~/.claude/ is tracked by a manifest — nothing is left behind on uninstall.
• CC source code is never modified. All capabilities come through the official extension system.

Full architecture →

---

Status — v0.1.0-alpha

This is an early alpha. The core pipeline works end-to-end, but rough edges exist.

Feature	Status
Multi-source search (arXiv + Semantic Scholar)	✅ Working
PDF download + parse (PyMuPDF)	✅ Working
Chunk + embed + FAISS index	✅ Working
Hybrid retrieval (vector + FTS5 + RRF)	✅ Working
Single-paper analysis	✅ Working
5 Claude Code skills	✅ Working
Global install / uninstall / toggle	✅ Working
Multi-paper comparison	🔜 Planned
Literature review generation	🔜 Planned
GROBID integration	🔜 Planned

Known limitations

• PDF parsing works best with text-based PDFs (arXiv-quality). Scanned/image PDFs are not yet supported.
• First MCP tool call has a cold-start delay (~2-3s) while the Python process loads.
• Embedding model (all-MiniLM-L6-v2) is English-optimized. Non-English papers may have lower retrieval quality.
• No Windows testing yet. macOS and Linux are the primary platforms.

---

MCP Tools

Ingest Server

Tool	Description
search_papers	Search arXiv + Semantic Scholar with deduplication
fetch_pdf	Download a PDF without triggering the full pipeline
ingest_paper	Full pipeline: download → parse → chunk → embed → index
batch_ingest	Batch ingest up to 100 papers
get_ingest_status	Check job or paper processing status

Retrieval Server

Tool	Description
retrieve_evidence	Hybrid search (vector + full-text + RRF ranking) with metadata filters

---

Documentation

Doc	Description
Architecture	Four-layer design, data flow, extension mechanisms
Schema & Tool Contracts	Data models, state machine, MCP tool interfaces
Claude Code Adaptation	Skills, agents, hooks, CLAUDE.md design
Implementation Plan	Sprint breakdown, test strategy, risk mitigation
Fork & Adapt Guide	How to repurpose this for patents, legal, finance, etc.
Configuration	Embedding models, LLM setup, environment variables
FAQ	Common questions about safety, scope, and alternatives

---

Contributing

Contributions welcome. See CONTRIBUTING.md.

If you've adapted this for another domain, open an issue to share.

License

MIT

---