8000 GitHub - pachterlab/paperpush: 📝 Automated manuscript validation and submission portal completion · GitHub
[go: up one dir, main page]
Skip to content
pachterlab
paperpush
Public

About

📝 Automated manuscript validation and submission portal completion

Resources

Readme
BSD-2-Clause license

Contributing

Contributing
Activity
Custom properties

Stars

211 stars

Watchers

5 watching

Forks

9 forks
Report repository
BranchesTags

Repository files navigation

PaperPush: Automated manuscript submission to journals, conferences, and preprint servers

Prepare manuscripts for submission to preprint servers, journals, and conferences with just a few commands. No need to spend hours verifying manuscript files for journal compliance and filling out submission portal forms manually. Just provide a manuscript directory and submission venue of interest, and PaperPush will validate the documents and fill out the submission portal for you.

PaperPush provides the following services:

  • A standardized system to share all data submitted to a journal/conference
  • Extensive venue-specific manuscript guideline checking including section lengths, reference hallucination, figure resolution, link validation, and anonymization — 124 distinct validation check types. The checks in a report depend on the venue and files. See the full list.
  • A central database of journal/conference manuscript requirements
  • Automated and fast submission portal filling with deterministic scripts
  • Free, open-source, actively-maintained, and never stores your data

tl;dr

Workflow to create the manuscript metadata (.sub) file, validate against author guidelines, and fill out the submission portal. Follow your favorite path:

Claude Code (other AI agents listed below):

  • /plugin marketplace add pachterlab/paperpush
  • /plugin install paperpush@paperpush
  • /paperpush-prepare-submission Prepare my manuscript in /PATH/TO/MANUSCRIPT/DIRECTORY for submission to VENUE with PaperPush.

Website:

  • Visit paperpush.onrender.com
  • Select the VENUE (or upload a .sub file)
  • Upload manuscript files and fill out the metadata fields
  • Click the blue "Validate" button to validate the files and metadata against author guidelines
  • Click the blue "Share" button to share the editable form with co-authors (or download and share the .sub file)
  • (If available) Click the "Fill out submission portal automatically" button and follow the instructions

CLI:

  • paperpush subfile VENUE # create a .sub file
  • Fill out VENUE.sub.txt
  • paperpush validate VENUE.sub.txt # validate the files and data in VENUE.sub.txt
  • Share VENUE.sub.txt with co-authors (it can be viewed in a text editor, with paperpush web VENUE.sub.txt, or via upload onto paperpush.onrender.com)
  • (If available) paperpush login VENUE # log in to the VENUE submission portal
  • (If available) paperpush submit VENUE.sub.txt # fill out the VENUE submission portal with information in VENUE.sub.txt

Website

paperpush.onrender.com: prepare a submission in your browser, validate it, and share the editable form with co-authors — no install needed.

Install

pip install paperpush["all"]  # Recommended — for AI API usage, MCP server, local web deployment, and additional manuscript validation checks
pip install paperpush  # basic CLI usage

(Required for submit): To install the playwright dependency and the required chromium browser, run:

playwright install chromium

Use with AI

Install the paperpush skills for your agent, so it knows how to autofill, validate, and submit:

Claude Code (two separate prompts):

/plugin marketplace add pachterlab/paperpush

/plugin install paperpush@paperpush

Codex:

codex plugin marketplace add pachterlab/paperpush
codex plugin add paperpush@paperpush

From a pip install (any agent):

paperpush install-skills                 # Claude Code, every project (~/.claude/skills)
paperpush install-skills --agent codex   # Codex (~/.codex/skills)
paperpush install-skills --dest DIR      # any other agent's skills directory

Then ask:

/paperpush-prepare-submission Prepare my manuscript in /PATH/TO/MANUSCRIPT/DIRECTORY for submission to VENUE with PaperPush.

See docs/example-session.md for a full worked example of this flow.

Quickstart

Use the agent skill /paperpush-prepare-submission to run this entire pipeline.

  1. paperpush subfile VENUE: creates a file VENUE.sub.txt that is a template for the VENUE submission. Fields are grouped into the same sections for every venue (manuscript type, files, details, authors, reviewers, declarations, additional); add --venue-order to list them in the order the venue's portal asks for them instead.
  2. fill out VENUE.sub.txt: Open VENUE.sub.txt in a text editor to edit manually, or run paperpush web VENUE.sub.txt to edit in a web browser. Use the agent skill /paperpush-autofill My manuscript files are in /PATH/TO/MANUSCRIPT/DIRECTORY. Fill out VENUE.sub.txt or the command paperpush autofill --engine api -p /PATH/TO/MANUSCRIPT/DIRECTORY ... VENUE.sub.txt (API) to automatically fill from the manuscript directory with AI. paperpush autofill requires the provider's API key. The AI agent may not be able to fill out all fields if some information is not in the manuscript directory.
  3. paperpush validate VENUE.sub.txt: run the pre-submission checks on the filled VENUE.sub.txt. Use the agent skill /paperpush-validate or the CLI flag --ai (API) to run checks with AI. The AI checks require the provider's API key. To check files before making a .sub, name them instead: paperpush validate --manuscript main.tex --title-page title.tex --figures fig1.png fig2.png runs the checks that apply to any manuscript (links, references, hidden text, citation order, prose, ...), and adding --venue VENUE checks them against that venue's author guidelines too. Use the agent skill /paperpush-fix to fix the issues validate finds: it edits the manuscript sources and the .sub, validates again until nothing fixable is left, and reports what needs your decision.
  4. paperpush login VENUE: log in to the VENUE submission portal.
  5. paperpush submit VENUE.sub.txt: Fill out the VENUE submission portal. Will not actually submit the manuscript. We highly recommend reviewing the submission form in the venue portal before clicking submit. Use the agent skill /paperpush-submit to run login and submit on a .sub file. Use the agent skill /paperpush-portal-debug or the CLI flag --ai (API) to have AI fix any issues that may arise. Ignore validation checks with the --skip-validate flag.

Helper commands:

  • paperpush venues: List supported venues. Filters combine:

    • --validate: only venues paperpush can validate a manuscript against.
    • --submit: only venues that also support automated submission portal filling.
    • -k/--keywords KW[,KW...]: only venues tagged with any of these subject keywords (e.g. biology,genetics).
    • -t/--type TYPE: only venues of this kind (preprint, journal, or conference; repeatable).
    • --columns COL[,COL...] / --hide-columns COL[,COL...]: choose which columns to show (slug, venue, keywords, type, link, validate, submit).

    For example, paperpush venues --submit -t journal -k biology lists the biology journals paperpush can submit to.

  • paperpush pick-venue: List supported venues that are a good thematic fit for your manuscript. Give it the manuscript's keywords (pick-venue hippocampus, place cells; a keyword can be a venue subject such as immunology), the manuscript itself (pick-venue manuscript.pdf), or its --title and --abstract, which are matched against each venue's subject keywords (--venue-name searches by name instead); add --ai (API) for an LLM's ranking with a reason for each venue. Note that this only searches the venues supported in PaperPush; and it only checks for thematic fit, not impact or likelihood of acceptance.

  • paperpush update-venues: Update the venue data (venues.json, submission_forms.json, manuscript_requirements.json) from the remote venue-data branch.

  • paperpush requirements VENUE: print VENUE's author guidelines, if available.

  • paperpush options VENUE.FIELD: print the allowed values for FIELD in VENUE's submission form.

  • paperpush web VENUE.sub.txt: open a sub file in a local deployment of the web application

See the YouTube tutorial PaperPush Tutorial

Documentation

paperpush.readthedocs.io

Supported venues

Preprint servers

Venue Slug Validate + basic .sub Submit + full .sub
arXiv arxiv ✅ ✅
bioRxiv biorxiv ✅ ✅
medRxiv medrxiv ✅ ✅

Journals

Venue Slug Validate + basic .sub Submit + full .sub
AJHG ajhg ✅
Bioinformatics bioinformatics ✅ ✅
BMC Bioinformatics bmc_bioinformatics ✅ ✅
BMC Biology bmc_biology ✅
BMC Genomics bmc_genomics ✅
BMC Medicine bmc_medicine ✅
The BMJ bmj ✅
Cell cell ✅ ✅
Cell Genomics cell_genomics ✅ ✅
Cell Reports cell_reports ✅
Cell Reports Methods cell_reports_methods ✅
Cell Stem Cell cell_stem_cell ✅
Cell Systems cell_systems ✅ ✅
Combinatorica combinatorica ✅ ✅
Communications Biology communications_biology ✅
Discrete Mathematics discrete_mathematics ✅ ✅
eLife elife ✅
European Radiology european_radiology ✅
Frontiers in Bioinformatics frontiers_bioinformatics ✅
Frontiers in Genetics frontiers_genetics ✅
Frontiers in Immunology frontiers_immunology ✅
Genome Biology genome_biology ✅ ✅
Genome Medicine genome_medicine ✅
Genome Research genome_research ✅
IEEE TMI ieee_tmi ✅
IEEE TNNLS ieee_tnnls ✅
IEEE TPAMI ieee_tpami ✅
iScience iscience ✅
JAMA jama ✅
JMLR jmlr ✅
JNM jnm ✅
The Lancet lancet ✅
Lancet Digital Health lancet_digital_health ✅
Medical Image Analysis medical_image_analysis ✅
Molecular Cell molecular_cell ✅
NAR Cancer nar_cancer ✅
NAR Genomics and Bioinformatics nar_genomics_bioinformatics ✅
Nature nature ✅ ✅
Nature Biomedical Engineering nature_biomedical_engineering ✅ ✅
Nature Biotechnology nature_biotech ✅ ✅
Nature Cell Biology nature_cell_biology ✅
Nature Communications nature_communications ✅
Nature Computational Science nature_computational_science ✅
Nature Genetics nature_genetics ✅
Nature Machine Intelligence nature_machine_intelligence ✅ ✅
Nature Medicine nature_medicine ✅
Nature Methods nature_methods ✅ ✅
Nature Neuroscience nature_neuroscience ✅
Nature Structural & Molecular Biology nature_structural_molecular_biology ✅
NEJM nejm ✅
Neuron neuron ✅
npj Digital Medicine npj_digital_medicine ✅
Nucleic Acids Research nucleic_acids_research ✅ ✅
Patterns patterns ✅
PLOS Biology plos_biology ✅
PLOS Computational Biology plos_compbio ✅ ✅
PLOS Genetics plos_genetics ✅
PLOS Medicine plos_medicine ✅
PLOS ONE plos_one ✅
PNAS pnas ✅
Radiology radiology ✅
Radiology: Artificial Intelligence radiology_ai ✅
Science science ✅ ✅
Science Advances science_advances ✅ ✅
Science Immunology science_immunology ✅ ✅
Science Robotics science_robotics ✅ ✅
Science Signaling science_signaling ✅ ✅
Science Translational Medicine science_translational_medicine ✅ ✅
Scientific Reports scientific_reports ✅
TMLR tmlr ✅

Conferences

Venue Slug Validate + basic .sub Submit + full .sub
ACL Rolling Review acl_arr ✅
CVPR 2027 cvpr_2027 ✅

View the list on the command line with paperpush venues.

Venues are added (for validate) and updated (for validate and submit) daily. paperpush update-venues updates immediately.

New venues are added for submit with paperpush releases - pip install -U paperpush.

Adding new venues

Each venue is listed in paperpush/venues.json (the master list of venues and their general metadata), paperpush/manuscript_requirements.json (the manuscript guidelines), and paperpush/submission_forms.json (the fields the portal asks for). The script for automatic venue login and submission lives in /paperpush/venues/PLATFORM/VENUE.py in a VENUE class with methods login and submit. See CONTRIBUTING.md and DEVELOPMENT.md for more details.

What is a .sub file

The .sub file is the yaml-like text file that contains all metadata and file paths required to upload a manuscript onto a venue's submission portal. An example snippet is shown below. In this case, you would provide "/PATH/TO/MANUSCRIPT.pdf", "TITLE", and "HERE IS THE ABSTRACT".

@venue: venue

# Manuscript file (file, REQUIRED)
#   Path to the submission.
manuscript_file: /PATH/TO/MANUSCRIPT.pdf

# Title (text, REQUIRED)
#   The full title of the article.
title: TITLE

# Abstract (textarea, REQUIRED)
#   Plain-text abstract, at least 20 characters
abstract: |
  HERE IS THE ABSTRACT

MCP server

To drive paperpush from any MCP client — Claude Desktop, an IDE extension — run it as an MCP server:

pip install 'paperpush[mcp]'
{
  "mcpServers": {
    "paperpush": {
      "command": "paperpush-mcp"
    }
  }
}

The server exposes the whole pipeline as tools. See AGENTS.md for the tool list and the contract agents should follow.

AI Skills

Skill Use it to
/paperpush-prepare-submission go from a manuscript directory to a filled-in portal (autofill, validate, submit)
/paperpush-autofill fill a .sub from the manuscript files
/paperpush-validate run every check, including the ones that need a reader
/paperpush-fix fix what validate flags (in the .tex/.docx sources and the .sub), re-validate until nothing fixable is left, and report what needs the author
/paperpush-submit log in and fill in the portal from a ready .sub (optionally skipping validation) — invokes portal-debug if it stalls
/paperpush-portal-debug get a stalled paperpush submit run unstuck
/paperpush-add-venue-validate add or refresh a venue's author guidelines (contributors)
/paperpush-add-venue run /paperpush-add-venue-validate and add login and submit support for a venue, with tests (contributors)

For AI agents

If you are an AI agent asked to submit a manuscript on the user's behalf, read AGENTS.md — or, if you are working from a pip install rather than a clone of this repo, run paperpush --agent-guide, which prints the same document from the copy that shipped with the installed version. It describes how to run the full pipeline while doing your own field extraction (reading the manuscript and writing a values.json for the default --engine manual) rather than relying on the API-backed engine. It also asks the agent to check paperpush login --list before it starts, and to tell you right away if you still need to run paperpush login <venue> yourself — that sign-in is interactive and belongs in your terminal. Agents that support skills should install them (see Use with AI); AGENTS.md lists what each skill does and when to use it.

FAQ

How does PaperPush work?

Supported venues are listed in paperpush/venues.json, their submission form data are in paperpush/submission_forms.json, and their author guidelines are in paperpush/manuscript_requirements.json. paperpush subfile generates a file from the form for the specified venue. The file can be filled out manually, or with the help of an LLM via paperpush autofill. The manuscript documents are validated with paperpush validate. The submission portal for a selected venue is filled out with the information from this file with a paperpush submit. This runs a Playwright script that is written specifically for each supported venue.

The repository says that it supports a given venue, but it fails when I try. Why is that?

Here are a few possibilities, in order of decreasing ease of resolution:

  • Sometimes, submission portals can be a bit funny, and the solution can be as simple as retrying the command 1-2 more times.
  • The submission portal is having server issues. You can try logging in to the portal manually to see if it is working, as well as on a different browser and at a different time.
  • The sub file has an option that we did not anticipate. You can try running the unit test for the venue with pytest tests/test_submit.py --run-portal -s --venue VENUE. If this passes, then it indicates an option in the sub file is not being handled correctly. If this fails, then it indicates that the submission portal has changed since the last time the venue was tested. In either case, please open an issue with the error message.
  • The submission portal has changed since the last time the venue was tested. You can run the unit test listed above to see if this is the case. If so, please open an issue with the error message.

I do not see my venue in the supported list. Is it possible to add a venue?

Yes! See CONTRIBUTING.md if you would like to add a journal yourself, and feel free to ask any questions in the Discussion forum.

Does PaperPush press submit for me?

No. PaperPush will bring you to one of the final steps on your venue of interest, but it will never actually press submit. I always recommend viewing any compiled PDFs and entered information to ensure accuracy and acknowledgment of guidelines.

Does every venue have a unique submission portal?

No — in fact, many share the same type of platform. PaperPush has a unique Playwright script for each supported venue, but many venues share the same submission platform. The big ones are Editorial Manager (including the Cell family and PLOS family), ScholarOne Manuscripts, eJournalPress, Snapp, and OpenReview (for many computer science conferences). The submission script may be highly similar for venues that share the same platform, so check the folders within paperpush/venues to see which venues share the same submission platform. See screenshots of each of the major supported venues in docs/portal_screenshots to see what each submission portal looks like.

How long does it take to add a new journal?

It depends on the complexity of the submission portal and your comfort with coding, but I would say roughly 1-3 hours manually. AI tools with the paperpush skills can potentially do this in under 20 minutes.

Can I vibe code a new journal?

Yes, with /paperpush-add-venue (see CONTRIBUTING.md). AI agents can navigate submission portals and write the Venue class for login and submit, but it can take a lot of tokens and may stall at times, so some human oversight helps. In my experience, LLMs can make the code a bit verbose and abstract away some of the action names, which may be harder to read/maintain in my opinion, but this is just stylistic. My favorite code style is in arxiv.py.

License

This project is licensed under the BSD-2 License - see the LICENSE file for details.

Developed by Joe Rich

About

📝 Automated manuscript validation and submission portal completion

Resources

Readme
BSD-2-Clause license

Contributing

Contributing
Activity
Custom properties

Stars

211 stars

Watchers

5 watching

Forks

9 forks
Report repository

Releases

Packages

Contributors

Languages
0