PaperFit: A Vision-in-the-Loop LaTeX Repair Agent for Claude Code, Codex and Cursor
📄 [Skill] Vision-in-the-loop LaTeX typesetting agent — auto-compile, render, diagnose, and fix paper layouts
At a glance
- What is it?
- PaperFit wraps a compile, render, diagnose, patch, re-render loop around a paper project so a coding agent can fix layout defects instead of only compile errors. The interesting part is the gatekeeper and the content-integrity rules, not the marketing claim of automatic typesetting.
- Who is it for?
- Adopt PaperFit if you already drive Claude Code, Codex or Cursor on a paper repository and want the compile-render-diagnose-patch loop plus a visual gate before submission; skip it if you have no working LaTeX toolchain, no Poppler, or no willingness to let an agent rewrite .tex source.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 86 days ago.
- What is it written in?
- Mainly TeX, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap PaperFit targets: a clean compile is not a clean page
LaTeX exits with status zero and still produces a paper nobody wants to read. The README lists the failure modes it cares about: floats stacked on top of each other, large holes in two-column pages, inconsistent table styling, formulas or tables running past the margin, and objects drifting after a template swap. None of these appear in the .log file in a form a text-only pass can reliably fix. A log line about an overfull hbox tells you a box is too wide; it does not tell you whether the real problem is a column specification, a caption length, or a float that should have been moved. PaperFit's stated audience is the author who already has an agent host open in the paper directory and would rather describe the goal in a sentence than hand-assemble a script chain. The README is explicit that the tool does not write the paper; it takes over the repetitive cycle of looking at the page, editing the source, and looking again.
The loop: compile, render, diagnose, patch, re-render, gate
The workflow in the README is a fixed sequence. A LaTeX project is compiled and its logs parsed. The resulting PDF is rendered into page images. Those images feed a visual diagnosis stage. A repair plan is produced at the source level, the .tex is patched, and the project is compiled and rendered again. A gatekeeper step then decides whether to keep repairing or to deliver. The important detail is the ordering: the gate sits after re-rendering, so a patch that fixes one defect while creating another does not pass. The README states plainly that visual inspection is a required step before delivery and that PaperFit will not declare typesetting finished just because compilation succeeded. Diagnosis is organized by a Visual Typesetting Optimization taxonomy with five categories: A covers space utilization (widows, orphans, last-page whitespace, unbalanced two-column heights, large holes), B covers floats (position, size, stacking, span, relationship to body text), C covers consistency across tables, figures, captions, spacing and style, D covers overflow and alignment including overfull boxes, formula breaking and over-wide tables, and E covers template migration such as single-to-double column changes and package compatibility. The full definitions live in config/vto_taxonomy.yaml. A shared vocabulary matters here because the repair stage needs to map a named defect class to a named fix strategy rather than to an ad hoc edit.
Installing PaperFit into an agent host
The prerequisites are Node.js 18 or newer, Python 3.8 or newer, Poppler for PDF metadata and page rendering, and a LaTeX toolchain such as tectonic or pdflatex. On macOS the README gives brew install poppler. The npm path is npm install -g paperfit-cli followed by paperfit-install --target claude. The installer also accepts --target codex, --target cursor --project /path/to/paper, and --target all. After installation the README recommends a health check and the Python dependencies: paperfit doctor --target claude, then pip3 install -r "$(npm root -g)/paperfit-cli/requirements.txt". A source install is git clone, npm install, then bash install.sh --local --target claude. There is also a Claude Code plugin marketplace route with /plugin marketplace add OpenRaiser/PaperFit and /plugin install paperfit@paperfit-vto, and Codex provider details are deferred to docs/CODEX_PROVIDER_SETUP.md. Development setup uses npm install, a virtualenv, pip install -r requirements.txt, and npm run verify. The CLI surface shown in the README is small: paperfit doctor, paperfit render paper.pdf --output data/pages, and paperfit status. Note that the README does not document a paperfit fix command. Repairs are driven through the agent conversation, and the CLI covers installation, health, rendering and state.
How you actually invoke it, and what the agent infers
PaperFit's recommended entry point is natural language, not memorized subcommands. In Claude Code you type /paperfit and then describe the goal, with shortcuts such as /fix-layout, /check-visual and /repair-table available. In Codex you phrase the request as "Use the paperfit agent to ..." and can return to the created thread with /agent. In Cursor, a project-level rule routes the request into PaperFit. The README claims PaperFit infers the main .tex file, the current template, the page budget and the repair path on its own, and only asks for more input when the project structure is unclear, the environment is missing, or the goal is ambiguous. That inference is the part I would treat with the most caution. Inferring the main .tex file is usually safe in a single-file project and much less safe in a repository with a supplement, a rebuttal folder, and several template variants. The README gives no documented override flag for the main file, so a misidentified root document is a real risk on multi-document repositories. Example prompts include analyzing main.tex for visual defects, running a full layout repair loop, performing visual inspection only, repairing a span table without resorting to resizebox, migrating to the CVPR template, and compressing the body to eight pages with minimal semantic change.
Content protection is the design decision that matters most
An agent that edits .tex source to make pages look better can make the paper worse in ways that are hard to notice. PaperFit's README addresses this with a stated content-integrity protocol. It says the tool will not silently delete figures, tables, captions, labels, citations or experimental results. It says \resizebox and \scalebox are not used as the default means of compressing a table, and that layout-level approaches come first: table*, tabularx, column-width restructuring, and float rearrangement. Semantic edits must be minimal, auditable, and retain the basis for the change. The protocol file is protocols/content-integrity-protection.md. These are policy statements in the documentation, not verified runtime guarantees, and the README does not describe a machine-checkable enforcement mechanism beyond the gatekeeper stage. Still, the choice to name the forbidden commands explicitly is more useful than a vague promise, because it tells you what to grep for in a diff after a repair run. If you use PaperFit on a submission, review the resulting diff rather than the rendered PDF alone; a page can look fine while a caption has been quietly shortened.
Where PaperFit is the wrong tool
PaperFit assumes a working LaTeX toolchain, Poppler, Node.js 18 or newer and Python 3.8 or newer. If your paper only builds inside a specific Docker image or a university cluster with a pinned TeX Live, the compile and render steps may not reproduce what you actually submit, and the visual diagnosis will be based on a PDF that is not your submission PDF. The tool is also a poor fit for repositories where the layout problem is not in the source at all, such as a journal class file you are not permitted to modify, or a camera-ready process that re-typesets your source on the publisher's side. The README's own framing rules out another case: it does not write the paper. If the real problem is that a section is unclear or a result is missing, no amount of float rearrangement helps. Finally, the README carries no release history, no versioned changelog in the supplied material, and describes the project status as active development. There is no evidence in the material about how often the visual diagnosis is correct, and the case images are presented as effect demonstrations rather than as a measured evaluation.
Alternatives and the actual difference in approach
The obvious comparison is latexmk or a plain build script plus a PDF viewer. latexmk reruns the compiler until cross-references settle; it is deterministic, fast, and does not need an agent host or a Python environment. Its output is a PDF and a log, and the judgement about whether the page looks right stays with you. PaperFit inserts a rendering and diagnosis stage between the build and the decision, and then acts on the diagnosis by editing source. That is the whole difference: latexmk answers "does it compile and are references stable", PaperFit attempts to answer "does the page look acceptable, and if not, which source line do I change". The cost of that extra stage is a nondeterministic agent in the loop and a dependency on Poppler plus page-image rendering. A second comparison is a manual pre-submission checklist: open the PDF, scan for overfull boxes, check float placement, check table styles. That is slower and does not scale to a template migration across dozens of pages, but it produces no source edits you did not approve. PaperFit's value is highest exactly where the manual pass is most tedious, which is the page-length compression and the template migration cases named in the README's suitable-scenarios list.
Maintenance, licence and what to verify first
PaperFit is MIT licensed, which permits commercial and academic use, modification and redistribution provided the copyright notice and licence text are preserved. That is a permissive arrangement, and it is worth noting that the repository's primary language is TeX while the installer and CLI are Node.js and the supporting scripts are Python, so the licence covers a mixed-language tree. This is not legal advice; if you redistribute a modified PaperFit inside a product, read the MIT text and your institution's rules yourself. On maintenance cost, the material shows no releases, so there is no versioned upgrade path to reason about, only the main branch and the documented install and update references in docs/RELEASE_AND_LOCAL_UPDATE.md. Upgrading therefore means re-running the installer or pulling the repository, and re-running paperfit doctor --target claude afterwards to confirm the host integration still resolves. The practical verification order I would use: confirm the toolchain by building your paper without PaperFit first, run paperfit doctor, run paperfit render on your own PDF and check that the page images match the PDF, then run one narrow task such as the table repair prompt before attempting a full migration. Keep the .tex under version control so the gatekeeper's edits are reviewable as a diff.
Editorial conclusion
Adopt PaperFit if you already drive Claude Code, Codex or Cursor on a paper repository and want the compile-render-diagnose-patch loop plus a visual gate before submission; skip it if you have no working LaTeX toolchain, no Poppler, or no willingness to let an agent rewrite .tex source. Before trusting it, run paperfit doctor --target claude, then paperfit render on your own PDF and compare the rendered pages against the defects PaperFit reports, because the README shows no release history and no verification of its diagnostic accuracy.
Community notes