
claude-paper
A plugin for studying research papers with automated material generation, code demos, and a web viewer
- version
- 1.2.1
- GitHub stars
- 360
Install
/plugin install claude-paper@claude-paperRun it inside Claude Code after adding the marketplace with /plugin marketplace add alaliqing/claude-paper.
Contents
Discovered from sourceSkills 3
Paper Study Workflow
Invoke this skill with a paper PDF path.
Language Detection: Detect the user's language from their input and generate ALL materials in that language.
- Example: User says "我们学习一下这篇论文吧" → Generate materials in Chinese
- Example: User says "Let's study this paper" → Generate materials in English
Core Philosophy
Primary Objective: Facilitate deep conceptual understanding and research-level thinking.
Secondary Objective: Create a structured, reusable paper knowledge system.
This workflow is not just for summarizing — it builds a learning environment around the paper.
Step 0: Check Dependencies (First Run Only)
if [ ! -f "${CLAUDE_PLUGIN_ROOT}/.installed" ]; then
echo "First run - installing dependencies..."
cd "${CLAUDE_PLUGIN_ROOT}"
npm install || exit 1
# Install Python dependencies for image extraction
python3 -m pip install pymupdf --user 2>/dev/null || pip3 install pymupdf --user 2>/dev/null || echo "Warning: Failed to install pymupdf"
touch "${CLAUDE_PLUGIN_ROOT}/.installed"
echo "Dependencies installed!"
fi
Recommended:
- Node >= 18
- Python 3 with pip (for image extraction)
Step 1: Download and Parse PDF
Supports multiple input formats:
- Local path:
~/Downloads/paper.pdf - Direct PDF URL:
https://arxiv.org/pdf/1706.03762.pdf - arXiv URL:
https://arxiv.org/abs/1706.03762
Step 1a: Check input type and download if URL
USER_INPUT="<user-input>"
# Check if input is a URL (starts with http:// or https://)
if [[ "$USER_INPUT" =~ ^https?:// ]]; then
# Download PDF from URL
INPUT_PATH=$(node ${CLAUDE_PLUGIN_ROOT}/skills/study/scripts/download-pdf.cjs "$USER_INPUT")
else
# Use local path directly
INPUT_PATH="$USER_INPUT"
fi
For URLs, the download script will:
- Download PDFs to
/tmp/claude-paper-downloads/ - Convert arXiv
/abs/URLs to PDF URLs automatically - Validate that URLs point to PDF files
- Return the local file path for processing
For local paths, use the path directly without downloading.
Step 1b: Parse PDF
Extract structured information:
PARSE_OUTPUT_DIR=$(mktemp -d)
node ${CLAUDE_PLUGIN_ROOT}/skills/study/scripts/parse-pdf.js \
"$INPUT_PATH" \
--output-dir "$PARSE_OUTPUT_DIR"
The command prints a small, strict JSON summary to stdout and writes:
meta.json— title, authors, abstract, links, page count, and a context-safe content previewpaper.txt— complete extracted text without the 50k preview limit
Use paper.txt as the source for generating materials. Search it and read relevant sections as needed; do not treat meta.json.content as the complete paper when contentTruncated is true.
After choosing {paper-slug}, create the paper directory and copy both parser artifacts plus the original PDF:
mkdir -p ~/claude-papers/papers/{paper-slug}
cp "<metaPath-from-parser-output>" ~/claude-papers/papers/{paper-slug}/meta.json
cp "<fullTextPath-from-parser-output>" ~/claude-papers/papers/{paper-slug}/paper.txt
cp "$INPUT_PATH" ~/claude-papers/papers/{paper-slug}/paper.pdf
Generate exactly 2 tags in Step 2.5 and add them to the saved meta.json.
Fallback: If structured parsing fails, extract raw text and continue with degraded structure.
Step 2: Assess Paper Before Generating Materials
Before generating any files, evaluate:
-
Difficulty Level
- Beginner
- Intermediate
- Advanced
- Highly Theoretical
-
Paper Nature
- Theoretical
- Architecture-based
- Empirical-heavy
- System design
- Survey
-
Methodological Complexity
- Simple pipeline
- Multi-stage training
- Novel architecture
- Heavy mathematical derivation
This assessment determines:
- Whether to create method.md
- Whether to create .ipynb
- Explanation depth
- Code demo complexity
Step 2.5: Generate Exactly 2 Semantic Tags (Mandatory)
Before generating files, infer exactly 2 tags from semantic understanding of the paper.
Rules:
- Generate exactly 2 tags, no more and no less
- Tags must be distinct
- Each tag should be short (1-3 words)
- Avoid generic tags:
paper,research,ai,ml - Prefer one tag for problem/domain and one for method/core idea
Examples:
machine translation,self-attention3d detection,bev transformerprotein folding,structure prediction
Persist these 2 tags in both locations:
~/claude-papers/papers/{paper-slug}/meta.jsonastags~/claude-papers/index.jsonentry astags
Step 3: Generate Core Study Materials
Create folder:
~/claude-papers/papers/{paper-slug}/
Required Files
README.md
- What the paper is about (one paragraph)
- Difficulty level
- How to navigate materials
- Key takeaways
- Estimated study time
- Folder structure overview
summary.md
- Background context
- Problem statement
- Main contributions
- Key results
- Quantitative metrics
insights.md (Most Important)
- Core idea explained plainly
- Why this works
- What conceptual shift it introduces
- Trade-offs
- Limitations
- Comparison to prior work
- Practical implications
qa.md
15 questions:
- 5 basic
- 5 intermediate
- 5 advanced
Use this format:
### Question
<details>
<summary>Answer</summary>
Detailed explanation.
</details>
---
Conditional Files
method.md (Recommended for most papers)
Include:
- Component breakdown
- Algorithm flow
- Architecture diagram (ASCII if needed)
- Step-by-step explanation
- Pseudocode (balanced with explanation)
- Implementation pitfalls
- Hyperparameter sensitivity
- Reproduction risks
mental-model.md (Recommended for most papers)
- What type of problem is this?
- What prior knowledge is assumed?
- How it fits into the broader research map
- How to mentally categorize this work
reflection.md (Optional auto-generated)
- If I were to extend this paper
- What open problems remain
- What assumptions are fragile
- Where it might fail in practice
Step 4: Code Demonstrations (Mandatory)
At least one runnable demo must be created.
All code demos must be placed in:
~/claude-papers/papers/{paper-slug}/code/
Create the code directory first:
mkdir -p ~/claude-papers/papers/{paper-slug}/code
Guidelines:
- Self-contained
- Runnable independently
- Educational comments (explain why)
- Focus on core contribution
- Prefer clarity over completeness
Possible types:
- Simplified conceptual implementation
- Visualization script
- Minimal architecture demo
- Interactive notebook (.ipynb)
Name descriptively:
- model_demo.py
- vectorized_planning_demo.py
- contrastive_loss_visualization.ipynb
Avoid generic names.
Step 5: Generate Interactive HTML Explorer
Create a single self-contained HTML file for interactively exploring the paper's core concepts.
Output path:
~/claude-papers/papers/{paper-slug}/index.html
Requirements
- Single HTML file, all CSS/JS inline, zero external dependencies
- Uses real data from the paper (actual metrics, hyperparameters, comparisons) — never invent numbers
- Must work in a sandboxed iframe (no external fetches, no localStorage)
Guidelines
Choose the interaction pattern that best fits the paper — architecture diagrams, parameter explorers, result dashboards, formula breakdowns, comparison matrices, etc. Let the paper's content dictate the format rather than forcing a fixed layout, focusing on the core ideas of the paper.
Every interactive control (slider, toggle, dropdown) should visibly change the visualization. Include brief explanatory text alongside interactive elements to teach concepts.
Step 6: Extract Images
mkdir -p ~/claude-papers/papers/{paper-slug}/images
python3 ${CLAUDE_PLUGIN_ROOT}/skills/study/scripts/extract-images.py \
paper.pdf \
~/claude-papers/papers/{paper-slug}/images
Rename key images descriptively:
- architecture.png
- training_pipeline.png
- results_table.png
Step 7: Update Index
CRITICAL: Read existing index.json first, then append the new paper. Never overwrite the entire file.
If index.json does not exist, create:
{"papers": []}
Append new entry to the papers array:
{
"id": "paper-slug",
"title": "Paper Title",
"slug": "paper-slug",
"authors": ["Author 1", "Author 2"],
"abstract": "Paper abstract...",
"year": 2024,
"date": "2024-01-01",
"tags": ["tag-1", "tag-2"],
"githubLinks": ["https://github.com/..."],
"codeLinks": ["https://..."]
}
IMPORTANT: The index.json file must be located at:
~/claude-papers/index.json
Step 8: Relaunch Web UI
Invoke:
/claude-paper:webui
Step 9: Interactive Deep Learning Loop
After all files are generated:
Present to User:
-
Ask:
- What part is still unclear?
- Do you want deeper mathematical breakdown?
- Do you want implementation-level analysis?
- Do you want comparison with another paper?
-
Allow user to:
- Ask deeper questions
- Summarize their understanding
- Propose new ideas
If user asks deeper questions:
Generate a new file inside the same folder:
Examples:
- deep-dive-contrastive-loss.md
- math-derivation-breakdown.md
- comparison-with-transformers.md
- extension-ideas.md
If user provides their own summary:
- Refine it.
- Improve structure.
- Save as:
- user-summary-v1.md
If iterated:
- user-summary-v2.md
If user wants structured consolidation:
Create:
- consolidated-notes.md
- study-session-1.md
- exam-review.md
This makes the paper folder a growing knowledge node.
Quick Paper Summary Workflow
This skill generates a concise summary of a research paper's core ideas and key points.
When to use:
- You want to quickly understand what a paper is about
- You need the main contributions without deep technical details
- You're screening papers to decide which to study in depth
When NOT to use:
- You want comprehensive study materials (use
/claude-paper:studyinstead) - You need code demonstrations
- You want interactive visualizations
Language Detection: Detect the user's language from their input and generate ALL materials in that language.
- Example: User says "我们学习一下这篇论文" → Generate materials in Chinese
- Example: User says "Let's study this paper" → Generate materials in English
Step 0: Check Dependencies (First Run Only)
if [ ! -f "${CLAUDE_PLUGIN_ROOT}/.installed" ]; then
echo "First run - installing dependencies..."
cd "${CLAUDE_PLUGIN_ROOT}"
npm install || exit 1
# Install Python dependencies for image extraction
python3 -m pip install pymupdf --user 2>/dev/null || pip3 install pymupdf --user 2>/dev/null || echo "Warning: Failed to install pymupdf"
touch "${CLAUDE_PLUGIN_ROOT}/.installed"
echo "Dependencies installed!"
fi
Step 1: Download and Parse PDF
Supports multiple input formats:
- Local path:
~/Downloads/paper.pdf - Direct PDF URL:
https://arxiv.org/pdf/1706.03762.pdf - arXiv URL:
https://arxiv.org/abs/1706.03762
Step 1a: Check input type and download if URL
USER_INPUT="<user-input>"
# Check if input is a URL (starts with http:// or https://)
if [[ "$USER_INPUT" =~ ^https?:// ]]; then
# Download PDF from URL
INPUT_PATH=$(node ${CLAUDE_PLUGIN_ROOT}/skills/study/scripts/download-pdf.cjs "$USER_INPUT")
else
# Use local path directly
INPUT_PATH="$USER_INPUT"
fi
For URLs, the download script will:
- Download PDFs to
/tmp/claude-paper-downloads/ - Convert arXiv
/abs/URLs to PDF URLs automatically - Validate that URLs point to PDF files
- Return the local file path for processing
Step 1b: Parse PDF
Extract structured information:
PARSE_OUTPUT_DIR=$(mktemp -d)
node ${CLAUDE_PLUGIN_ROOT}/skills/study/scripts/parse-pdf.js \
"$INPUT_PATH" \
--output-dir "$PARSE_OUTPUT_DIR"
The command prints a small, strict JSON summary to stdout and writes:
meta.json— title, authors, abstract, links, page count, and a context-safe content previewpaper.txt— complete extracted text without the 50k preview limit
Use paper.txt as the source for the quick summary. Do not treat meta.json.content as the complete paper when contentTruncated is true.
Step 2: Generate Quick Summary
Create the paper folder:
mkdir -p ~/claude-papers/papers/{paper-slug}
cp "<metaPath-from-parser-output>" ~/claude-papers/papers/{paper-slug}/meta.json
cp "<fullTextPath-from-parser-output>" ~/claude-papers/papers/{paper-slug}/paper.txt
cp "$INPUT_PATH" ~/claude-papers/papers/{paper-slug}/paper.pdf
Generate quick-summary.md with the following structure:
# Quick Summary: [Paper Title]
## One Sentence
[One sentence that captures what the paper is about]
## Problem
[What problem does this paper solve? Why is it important?]
## Core Idea
[The key innovation explained in 2-3 sentences. What makes this paper novel?]
## Key Contributions
- [Contribution 1]
- [Contribution 2]
- [Contribution 3]
- [Contribution 4 if applicable]
## Main Results
| Metric | Value | Dataset/Benchmark |
|--------|-------|-------------------|
| [metric1] | [value] | [dataset] |
| [metric2] | [value] | [dataset] |
## Why It Matters
[Practical implications. How does this advance the field? What can we now do that we couldn't before?]
## Limitations
- [Limitation 1]
- [Limitation 2]
Guidelines for each section:
| Section | Length | Focus |
|---|---|---|
| One Sentence | 1 sentence | High-level summary |
| Problem | 2-3 sentences | Context and motivation |
| Core Idea | 2-3 sentences | The main innovation |
| Key Contributions | 3-5 bullets | What's new/novel |
| Main Results | 1 table | Quantitative metrics from the paper |
| Why It Matters | 2-3 sentences | Practical value |
| Limitations | 2-3 bullets | What the paper doesn't solve |
Total length: ~300-500 words (excluding results table)
Step 3: Update Index
CRITICAL: Read existing index.json first, then append the new paper. Never overwrite the entire file.
If index.json does not exist, create:
{"papers": []}
Append new entry to the papers array:
{
"id": "paper-slug",
"title": "Paper Title",
"slug": "paper-slug",
"authors": ["Author 1", "Author 2"],
"abstract": "Paper abstract...",
"year": 2024,
"date": "2024-01-01",
"tags": ["quick-summary"],
"githubLinks": ["https://github.com/..."],
"codeLinks": ["https://..."]
}
IMPORTANT: The index.json file must be located at:
~/claude-papers/index.json
Step 4: Relaunch Web UI
Invoke:
/claude-paper:webui
Step 5: Present Summary to User
After generating the summary:
-
Show the user the quick-summary.md content - Display the full summary
-
Offer next steps:
- "Would you like to study this paper in more depth? Use
/claude-paper:studyfor comprehensive materials." - "Do you have questions about specific parts of the paper?"
- "Would you like me to explain any section in more detail?"
- "Would you like to study this paper in more depth? Use
-
File location reminder:
- Summary saved to:
~/claude-papers/papers/{paper-slug}/quick-summary.md - Web UI available at:
http://localhost:5815
- Summary saved to:
Example Output
# Quick Summary: Attention Is All You Need
## One Sentence
This paper introduces the Transformer, a neural network architecture based entirely on attention mechanisms, achieving state-of-the-art results in machine translation.
## Problem
Sequence transduction models at the time (RNNs, LSTMs, GRUs) process data sequentially, limiting parallelization and struggling with long-range dependencies.
## Core Idea
Replace recurrent layers with self-attention mechanisms, enabling full parallelization during training and direct modeling of dependencies regardless of distance. The Transformer uses multi-head attention to jointly attend to information from different representation subspaces.
## Key Contributions
- First transduction model relying entirely on self-attention, no recurrence
- Multi-head attention mechanism for joint attention across subspaces
- Positional encodings to inject sequence order information
- Achieved 28.4 BLEU on WMT 2014 English-to-German (2+ BLEU improvement)
- Training was significantly faster than previous state-of-the-art
## Main Results
| Metric | Value | Dataset/Benchmark |
|--------|-------|-------------------|
| BLEU (EN-DE) | 28.4 | WMT 2014 |
| BLEU (EN-FR) | 41.8 | WMT 2014 |
| Training cost | 3.3 × 10^18 FLOPs | WMT 2014 EN-DE |
| Training time | 12 hours on 8 P100 | WMT 2014 EN-DE |
## Why It Matters
The Transformer eliminated recurrence, enabling massive parallelization and scaling. This architecture became the foundation for BERT, GPT, and virtually all modern large language models, fundamentally changing NLP and beyond.
## Limitations
- Self-attention has O(n²) complexity, limiting sequence length
- No explicit modeling of position beyond learned encodings
- Requires large amounts of training data
Notes
- This skill is intentionally minimal - it generates only the summary, no code demos, no interactive HTML, no deep-dive materials
- For users who want more, they can use
/claude-paper:studyto generate comprehensive materials - The summary should be self-contained and readable in under 5 minutes
- Focus on conceptual clarity over technical details
Start Web UI
This skill starts the Claude Paper web viewer using the production Nuxt.js server.
Step 1: Check and Install Dependencies (First Run Only)
Check if web dependencies are installed (with corruption check):
cd "${CLAUDE_PLUGIN_ROOT}/src/web"
if [ ! -d "node_modules" ]; then
echo "First run - installing web dependencies..."
npm ci
echo "Web dependencies installed!"
elif [ ! -f "node_modules/.package-lock.json" ] || [ ! -d "node_modules/nuxt" ]; then
echo "ERROR: node_modules is corrupted, performing clean install..."
rm -rf node_modules
npm ci
echo "Web dependencies installed!"
else
echo "Dependencies already installed"
fi
Step 2: Build Production Server (auto-rebuilds on plugin update)
Build if needed or if plugin version changed:
cd ${CLAUDE_PLUGIN_ROOT}/src/web
PLUGIN_VERSION=$(node -e "console.log(require('${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json').version)")
BUILD_VERSION=""
if [ -f ".output/.build-version" ]; then
BUILD_VERSION=$(cat ".output/.build-version")
fi
if [ ! -f ".output/server/index.mjs" ] || [ "$PLUGIN_VERSION" != "$BUILD_VERSION" ]; then
echo "Building production server (v${PLUGIN_VERSION})..."
npm run build
echo "$PLUGIN_VERSION" > .output/.build-version
echo "Build complete!"
else
echo "Production build is up to date (v${BUILD_VERSION})"
fi
Step 3: Check Port Availability
Ensure port 5815 is available (with version check restart):
# Get version info for comparison
PLUGIN_VERSION=$(node -e "console.log(require('${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json').version)")
BUILD_VERSION=""
if [ -f ".output/.build-version" ]; then
BUILD_VERSION=$(cat ".output/.build-version")
fi
if lsof -i :5815 > /dev/null 2>&1; then
echo "INFO: Port 5815 is already in use"
PID_FILE="/tmp/claude-paper-webui.pid"
if [ -f "$PID_FILE" ] && kill -0 $(cat "$PID_FILE") 2>/dev/null; then
# Check version match - restart if plugin was updated
if [ "$PLUGIN_VERSION" = "$BUILD_VERSION" ]; then
echo "Claude Paper web UI is already running (version ${PLUGIN_VERSION})"
echo "Access it at: http://localhost:5815"
exit 0
else
echo "Version mismatch: running ${BUILD_VERSION}, need ${PLUGIN_VERSION}"
echo "Stopping old server..."
kill $(cat "$PID_FILE") 2>/dev/null
sleep 2
rm -f "$PID_FILE"
echo "Old server stopped, will restart with new version"
fi
else
echo "ERROR: Port 5815 is occupied by another process"
exit 1
fi
fi
Step 4: Start Production Server
Start the server in background:
HOST=127.0.0.1 PORT=5815 node .output/server/index.mjs &
SERVER_PID=$!
# Save PID for later cleanup
echo $SERVER_PID > /tmp/claude-paper-webui.pid
echo "Server PID: $SERVER_PID"
Step 5: Verify Server Health
Wait for server to be ready:
timeout=10
while [ $timeout -gt 0 ]; do
if curl -s http://localhost:5815/api/papers > /dev/null 2>&1; then
echo "Server is ready!"
break
fi
sleep 1
timeout=$((timeout - 1))
done
if [ $timeout -eq 0 ]; then
echo "ERROR: Server failed to start properly"
kill $SERVER_PID 2>/dev/null
rm -f /tmp/claude-paper-webui.pid
exit 1
fi
Step 6: Inform User
Tell the user the web viewer is available and provide cleanup instructions:
Claude Paper web UI is now running!
Access it at: http://localhost:5815
To stop the server, run:
kill $(cat /tmp/claude-paper-webui.pid)
Commands 1
Your task
Start the Claude Paper web viewer using the production Nuxt.js server.
Step 1: Check and Install Dependencies (First Run Only)
if [ ! -f "${CLAUDE_PLUGIN_ROOT}/src/web/node_modules/.package-lock.json" ] || [ ! -d "${CLAUDE_PLUGIN_ROOT}/src/web/node_modules/@nuxt" ]; then
if [ ! -d "${CLAUDE_PLUGIN_ROOT}/src/web/node_modules/@nuxt" ]; then
echo "ERROR: node_modules is corrupted, performing clean install..."
cd "${CLAUDE_PLUGIN_ROOT}/src/web"
rm -rf node_modules package-lock.json
npm install
echo "Web dependencies installed!"
else
echo "First run - installing web dependencies..."
cd "${CLAUDE_PLUGIN_ROOT}/src/web"
npm install
echo "Web dependencies installed!"
fi
else
echo "Dependencies already installed"
fi
Step 2: Build Production Server (auto-rebuilds on plugin update)
cd ${CLAUDE_PLUGIN_ROOT}/src/web
PLUGIN_VERSION=$(node -e "console.log(require('${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json').version)")
BUILD_VERSION=""
if [ -f ".output/.build-version" ]; then
BUILD_VERSION=$(cat ".output/.build-version")
fi
if [ ! -f ".output/server/index.mjs" ] || [ "$PLUGIN_VERSION" != "$BUILD_VERSION" ]; then
echo "Building production server (v${PLUGIN_VERSION})..."
npm run build
echo "$PLUGIN_VERSION" > .output/.build-version
echo "Build complete!"
else
echo "Production build is up to date (v${BUILD_VERSION})"
fi
Step 3: Check Port Availability
# Get version info for comparison
PLUGIN_VERSION=$(node -e "console.log(require('${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json').version)")
BUILD_VERSION=""
if [ -f ".output/.build-version" ]; then
BUILD_VERSION=$(cat ".output/.build-version")
fi
if lsof -i :5815 > /dev/null 2>&1; then
echo "INFO: Port 5815 is already in use"
PID_FILE="/tmp/claude-paper-webui.pid"
if [ -f "$PID_FILE" ] && kill -0 $(cat "$PID_FILE") 2>/dev/null; then
# Check version match - restart if plugin was updated
if [ "$PLUGIN_VERSION" = "$BUILD_VERSION" ]; then
echo "Claude Paper web UI is already running (version ${PLUGIN_VERSION})"
echo "Access it at: http://localhost:5815"
exit 0
else
echo "Version mismatch: running ${BUILD_VERSION}, need ${PLUGIN_VERSION}"
echo "Stopping old server..."
kill $(cat "$PID_FILE") 2>/dev/null
sleep 2
rm -f "$PID_FILE"
echo "Old server stopped, will restart with new version"
fi
else
echo "ERROR: Port 5815 is occupied by another process"
exit 1
fi
fi
Step 4: Start Production Server
PORT=5815 node .output/server/index.mjs &
SERVER_PID=$!
# Save PID for later cleanup
echo $SERVER_PID > /tmp/claude-paper-webui.pid
echo "Server PID: $SERVER_PID"
Step 5: Verify Server Health
timeout=10
while [ $timeout -gt 0 ]; do
if curl -s http://localhost:5815/api/papers > /dev/null 2>&1; then
echo "Server is ready!"
break
fi
sleep 1
timeout=$((timeout - 1))
done
if [ $timeout -eq 0 ]; then
echo "ERROR: Server failed to start properly"
kill $SERVER_PID 2>/dev/null
rm -f /tmp/claude-paper-webui.pid
exit 1
fi
Step 6: Inform User
Claude Paper web UI is now running!
Access it at: http://localhost:5815
To stop the server, run:
kill $(cat /tmp/claude-paper-webui.pid)
Hooks 1
Sponsors
Details
- Marketplace
- alaliqing/claude-paper
- Source
- plugin
- Author
- alaliqing
- Category
- Development