open-academic-paper-machine

Open Academic Paper Machine

A Claude Code plugin that autonomously writes academic papers — from literature search to production-ready LaTeX/PDF.

v6.4.0 — Paper-vs-Code Audit. New /audit-paper command and audit-engine skill: static audit of a paper's empirical claims (datasets, models, hyperparameters, metrics) against the linked code repository. Classifies each claim as CONFIRMED / PARTIAL / MISSING / MISMATCH / NOT_AUDITABLE with file:line evidence. Complements /verify-citations (external sources) by checking own-work claims against own code. Inspired by Feynman's /audit.

Scope note. This project is a technical contribution: it explores what is possible with current LLM technology for academic paper production, not what is desirable or ethically permissible. The ethical, epistemological, and policy questions raised by AI-generated academic writing — authorship attribution, academic integrity, epistemic status, potential misuse — are important but outside the scope of this tool. They are addressed in the companion position paper (Blask & Funk, 2026).

Quick Start

# 1. Install the plugin
/plugin marketplace add TobiasBlask/open-paper-machine
/plugin install open-academic-paper-machine@open-paper-machine

# 2. Install dependencies
pip install paperbanana[google] academic-search-mcp

# 3. Set up your API key (free — https://aistudio.google.com/apikey)
echo 'GOOGLE_API_KEY="your-key"' > ~/.paperbanana.env
# Or per-project: echo 'GOOGLE_API_KEY="your-key"' > .env

# 4. Go
/write-paper The impact of generative AI on organizational decision-making

That's it. The plugin ships the academic-search MCP server, the PaperBanana direct Python API for figure generation, all 16 skill engines, 4 agents, 24 curated scientific skills, 20 slash commands, and the autonomous pipeline agent. Everything starts automatically.

Technical paper: The Open Academic Paper Machine: An Autonomous LLM Plugin for End-to-End Academic Paper Production (Blask, 2026) — describes the system architecture, design principles, and evaluation. LaTeX source in paper/.

Position paper: From Creator to Orchestrator? How an LLM Agent Wrote This Paper and What That Means for Science (Blask & Funk, 2026) — a position paper on AI-augmented knowledge production, orchestrated through human-AI interaction using this system. GitHub repo.

---

How It Works

The machine runs autonomously through 9 phases:

Phase	What Happens	Your Job
0. Idea Evaluation (v6.3.0)	Stress-test idea along 7 dimensions, conclusion-first test, PURSUE/REFINE/KILL verdict	Decide whether to proceed
1. Reconnaissance	4-6 search queries across 4 academic APIs, snowballing, deduplication	Check scope, redirect if needed
2. Framing	Theory selection, gap formulation, research questions, contribution statement	Confirm direction
3. Structure	Concept matrix, paper structure, word budget	Approve structure
4. Production	Write every section as complete paragraphs + generate figures	Read along, adjust
5. Assembly	Compile all sections, quality self-assessment, status report	Start review
6. LaTeX & PDF	Convert to arxiv-style LaTeX, resolve citations, compile PDF	Download and submit
7. Verification (opt.)	Fetch source abstracts/PDFs, verify each citation claim	Review flagged mismatches
8. Revision (repeatable)	Extract reviewer/co-author feedback, classify, implement changes, recompile + latexdiff	Approve change plan

Core principle: Before producing, evaluate. The machine gates the pipeline — not every topic deserves months of work. Then it makes decisions and presents results. You steer at checkpoints.

Phase 8 closes the loop: send an annotated PDF from your co-author or paste reviewer comments, and the review-engine extracts, classifies, and implements all changes — then recompiles and generates a visual diff. The cycle repeats (Round 1 → 2 → 3 → ...) until acceptance.

---

Requirements

Requirement	Version	Notes
Claude Code	Latest	CLI or IDE extension (VS Code / JetBrains)
Python	3.10+	For PaperBanana and academic-search MCP servers
LaTeX	Any recent	Optional — only needed for PDF compilation (/export-latex)
Google API key	Free	For AI figure generation — get one here

No Google API key? The plugin works fully without one — you just won't get AI-generated figures. The figure-engine falls back to matplotlib/seaborn. All other features (literature search, writing, LaTeX, revision, etc.) work independently.

---

Installation

What Gets Installed

The plugin bundles one MCP server that starts automatically, plus PaperBanana via direct Python API:

Component	pip package	What it does
academic-search (MCP)	academic-search-mcp	Searches Semantic Scholar, OpenAlex, CrossRef, arXiv. Snowballing, BibTeX/CSV export.
PaperBanana (direct API)	paperbanana	AI figure generation via Google Gemini. Multi-agent pipeline with iterative refinement. Based on Zhu et al. (2026).

The academic-search MCP server is configured in plugin.json and starts when Claude Code loads the plugin. PaperBanana is called via direct Python API (scripts/paperbanana_direct.py) — the MCP transport layer was removed in v6.3.0 due to persistent reliability issues (timeouts, silent failures).

Academic foundation: The figure generation pipeline implements the methodology from PaperBanana: Automating Academic Illustration for AI Scientists (Zhu et al., 2026). The MCP integration uses the community implementation at llmsresearch/paperbanana. See also the official research repo.

Step-by-Step

1. Add the marketplace and install the plugin:

/plugin marketplace add TobiasBlask/open-paper-machine
/plugin install open-academic-paper-machine@open-paper-machine

2. Install Python dependencies:

pip install paperbanana[google] academic-search-mcp

3. Configure your Google API key (needed for AI figure generation):

Get a free key at Google AI Studio, then set it up (choose one):

# Option A — Global (recommended, works across all projects):
echo 'GOOGLE_API_KEY="your-api-key-here"' > ~/.paperbanana.env

# Option B — Per-project:
echo 'GOOGLE_API_KEY="your-api-key-here"' > .env

Key loading priority: Environment variable → ~/.paperbanana.env → project .env. Never commit .env to version control. See .env.example for a template.

4. Install LaTeX (for PDF compilation):

# macOS
brew install --cask mactex-no-gui

# Ubuntu/Debian
sudo apt-get install texlive-full

5. Start writing:

/write-paper Your Paper Title Here

Cowork Setup

1. Download the latest release ZIP from GitHub Releases
2. In Cowork, open the Plugins panel and click "+" → upload the ZIP
3. Set GOOGLE_API_KEY in plugin settings (optional — only needed for AI figures)
4. /write-paper Your Paper Title

---

Idea Evaluation — Phase 0 (v6.3.0)

Most AI writing tools help you write papers. Phase 0 helps you decide which papers to write.

The previous pipeline took any topic and produced. Version 6.3.0 adds the missing gate: Is this paper the right use of my time? Based on Nicholas Carlini's research philosophy (How to Win a Best Paper Award) and the research-companion plugin by Andre Huang.

# Standalone idea evaluation
/evaluate-idea Can LLMs replace systematic literature reviews?

# Or just run /write-paper — Phase 0 runs automatically first
/write-paper The impact of generative AI on organizational decision-making

How It Works

Three specialist agents evaluate your idea before the pipeline commits to production:

Agent	Role	Output
Idea Critic	Adversarial stress-test along 7 dimensions	PURSUE / REFINE / KILL verdict
Research Strategist	Strategic viability: competition, timing, comparative advantage	Green / Yellow / Red flags
Brainstormer	Cross-field connections, assumption challenges, reframings	Alternative angles and extensions

The 7 Evaluation Dimensions

Dimension	Key Question	Signal
Novelty (RS1)	If you don't do this, how long until someone else does?	Weeks / Months / Years
Impact (RS2)	Can you write a compelling conclusion right now?	Low / Medium / High
Timing (RS8)	Is the field ready? Too early? Already crowded?	Too Early / Well-Timed / Too Late
Feasibility (RS4)	What's the riskiest assumption? Can you test it in a week?	High / Medium / Low Risk
Competition (RS7)	Who else is working on this? What's your advantage?	Crowded / Moderate / Open
Nugget (RS3)	Can you state the key insight in one sentence?	Clear / Fuzzy / Missing
Narrative	Can you tell a story that makes a skeptical reader care?	Compelling / Workable / Weak

The Conclusion-First Test

The decisive gate. Before investing, the engine writes the best-case conclusion: if everything works perfectly, what can this paper say? If the answer is hollow or generic — if it only says "our method achieves X% improvement" — the idea doesn't have enough impact. Kill it and move on.

Research Strategy Principles (RS1-RS8)

Eight principles guide evaluation (see principles/research-strategy.md):

• RS1 (Novelty Test): Favor problems where your unique skills create a months-to-years gap.
• RS2 (Conclusion-First Test): Write the conclusion before doing the research.
• RS3 (Nugget Test): One sentence. One idea. Every figure connects to it.
• RS4 (Fail Fast): Start with what's most likely to kill the project.
• RS5 (Kill Early): A working project with low impact is worse than a killed project.
• RS6 (Unreasonable Effort): Go to unreasonable lengths — but only AFTER RS4 and RS5.
• RS7 (Comparative Advantage): Research space is high-dimensional; find your unique corner.
• RS8 (Timing Awareness): Impact = skill x domain importance at this moment.

Evaluations persist to research-evaluations/*.md for cross-session continuity. Previously killed ideas are checked for changed conditions rather than re-evaluated from scratch.

---

Commands

Idea Evaluation (v6.3.0)

Command	Description
/evaluate-idea [topic]	Full idea stress-test — 7 dimensions, 3 agents, conclusion-first test, PURSUE/PARK/KILL verdict
/brainstorm [topic]	Creative brainstorming — cross-field connections, assumption challenges, alternative framings, wild cards