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:

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

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:

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:

The 7 Evaluation Dimensions

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)