LaTeX Look

latex-look — teach an agent to *see* your LaTeX

English · 简体中文

*Left: compiles with zero errors. Right: after five sentences a reader could say out loud — "remove the rules around the title", "this table is a grid, make it a booktabs table", "that link runs off the page", "the figure is too wide". Try it yourself in examples/broken-layout.*

A DeepSeek Harness plugin that adds exactly one tool: latex_look.

An agent that only reads .tex source is blind: a document can compile with zero errors and still look wrong. latex_look compiles the document, renders the page as an image, maps any spot on that page back to the exact source line, and diffs what your last edit changed — in a single call.

        ┌─────────────┐   latex_look   ┌──────────────┐

│ agent │ ─────────────► │ pdf → png │ │ (edits .tex)│ │ synctex │ └─────────────┘ ◄───────────── │ pixel diff │ ▲ image + line └──────────────┘ └─────────────── verification ───────────┘

Read the case study: a 215-page LaTeX book, read the way a reader reads it — 163 figures, 129 equations, six classes of defect that compile cleanly.

Why one tool, not three

Rendering, locating, and diffing are the *implementation*. The agent needs one coherent verb — "look at this page" — the same way a person does. latex_look compiles, renders, resolves, and diffs in a single call, so the loop is:

look → diagnose → edit .tex → look again → confirm the change → report

Install

Requires Node ≥ 18, a TeX engine (xelatex/lualatex/pdflatex/latexmk or tectonic), synctex, and ghostscript.

This repository is the bundle: package.json declares dsh.bundle.patch, and cordis.patch.yml inserts one row.

git clone https://github.com/fangchenghao/latex-look

Then install it into the current profile (in the Harness, via the plugin manager):

plugin_manager  action: install_bundle  target: /absolute/path/to/latex-look

That adds the row latex-look and registers the latex_look tool. Replacing the sources of an already-installed package needs a Harness restart to load a fresh module generation.

Published on npm as @fffangchenghao/dsh-latex-look, so the same row also installs straight from the registry:

plugin_manager  action: install_bundle  target: @fffangchenghao/dsh-latex-look

Updating

Two different facts, and the plugin reports them separately because confusing them is how an update goes missing:

A newer release exists. The registry is asked once a day, in the background; when something newer is published, one line is appended to a tool reply. An offline machine sees nothing at all, and an unreachable registry is never reported as "up to date".

A newer release is already installed. This is the one that silently bites. An updater replaces the package directory while the old code keeps running, so the running code goes on reading its version out of a package.json that was swapped underneath it — it reports the *new* number while executing the *old* code, and everything looks current. The plugin therefore remembers the version it started with, re-reads the disk at most once a minute, and when the two disagree says so:

note: @fffangchenghao/dsh-latex-look 0.4.2 is installed on disk, but this process is

still running 0.4.1 — restart DeepSeek Harness to load it.

The plugin does not update itself. Replacing the files of a running process is the profile's job, not a tool's: an updater plugin already installed in the profile does it, or you do it by hand. When the plugin can tell which profile it was installed into, it prints the exact command — the profile name is read off its own path, because they are called desktop and web and a guess sends you to an install that does nothing:

dsh plugin --profile desktop add @fffangchenghao/dsh-latex-look@latest

core.mjs is not hot-reloaded, so a plugin update takes effect on the next start of the harness, never mid-session.

From a checkout, both questions are available directly:

node bin/latex-look.mjs --version

node bin/latex-look.mjs --check-update

Releasing

Tagging v* runs the test suite on Ubuntu with TeX and Ghostscript installed, verifies the tag matches package.json, and publishes to npm. The token comes from the NPM_TOKEN repository secret.

Optional: the knowledge skill

The tool gives the agent eyes. SKILL.md gives it the LaTeX knowledge to act on what it sees — a symptom → cause → fix playbook (a rule you want gone is usually \pagestyle/fancyhdr, not a stray \hline). Copy or symlink it into the skills root:

mkdir -p ~/.dsh/skills/latex-look

ln -sf "$PWD/SKILL.md" ~/.dsh/skills/latex-look/SKILL.md

CLI, for humans and for testing

node bin/latex-look.mjs book.tex --page 37

node bin/latex-look.mjs book.tex --text "表3.1" node bin/latex-look.mjs book.tex --page 12 --compare previous --json node bin/latex-look.mjs book.tex --page 1 --audit # what did the last edit break, anywhere?

The CLI runs the same engine as the plugin and needs no Harness, which makes it the fast way to check a change without reloading anything.

MCP server, for Claude Desktop, Cursor and Codex

The same engine ships as a Model Context Protocol server, so a client that has never heard of DSH can use it. It is the same look() and the same words in the reply — the plugin is the Harness shape, this is the universal one.

{

"mcpServers": { "latex-look": { "command": "npx", "args": ["-y", "@fffangchenghao/dsh-latex-look", "mcp"] } } }

Put that in claude_desktop_config.json (Claude Desktop), ~/.cursor/mcp.json (Cursor), or as a TOML block in ~/.codex/config.toml:

[mcp_servers.latex-look]

command = "npx" args = ["-y", "@fffangchenghao/dsh-latex-look", "mcp"]

It exposes one tool, latex_look, with the same parameters as everywhere else: file, page, text, pointX/pointY, compare, audit, sequence, dpi. Pages come back as image content blocks, so the model sees the page itself.

Requirements are the usual ones — a TeX engine and ghostscript on PATH:

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

sudo apt install texlive-xetex ghostscript # Debian/Ubuntu winget install MiKTeX.MiKTeX ArtifexSoftware.GhostScript # Windows

On Windows nothing has to be added to PATH: the plugin asks for gswin64c (that is Ghostscript's real name there), and when that is not found it looks in C:\Program Files\gs\gs*\bin, plus the TeX Live, MiKTeX and TinyTeX install directories. If you would rather be explicit, point PATH at C:\Program Files\gs\gs10.05.1\bin and it is used first.

Nothing is uploaded: every call compiles the document that is already on your disk.

Listed in the official MCP Registry as io.github.fangchenghao/latex-look, so clients that search the registry can install it by name, and on awesome-mcp-servers.

Tests

Three suites run on a clean checkout — they create their own fixtures and compile real documents, so expect a few minutes:

node test/smoke.mjs           # unit level: problem parsing, PPM, raster diff, aux detection

node test/scenarios.mjs # 52 end-to-end cases driven through index.js node test/scenarios-deep.mjs # 29 cases: multi-file papers, beamer, twocolumn, images,

engine switching, the build cache, hostile inputs

node test/book-scenarios.mjs # 15 cases against a real 208-page book (164 .tex files) node test/book-tasks.mjs # 18 real editing tasks on the same book (see below) LATEX_LOOK_BOOK=/pristine/copy node test/book-tasks.mjs # point it at an unedited copy

The book suite needs a real book and is skipped unless you point it at one:

LATEX_LOOK_BOOK=/path/to/book node test/book-scenarios.mjs

These two suites matter most, because a real book is root → \input{main} → \input{chap1}, with a custom .sty, 181 figures, a glossary and fancyhdr page furniture.

book-scenarios checks the machinery on that book. book-tasks checks the *requests*: each case is a sentence a user would say, applied to the copy and then verified the way an agent verifies it — look, diff against the previous build, and confirm the change is where the edit acts:

Nothing in these cases is asserted about how the change *looks* — that is what the image is for. The assertions are: the build succeeded, a diff exists, and its bounding box is in the region the edit acts on.

Both end-to-end suites stub only @deepseek-ai/dsh-tools (it exists solely inside the Harness) and call the real execute with real arguments, so they exercise the argument handling and the exact text the model reads — not just lib/core.mjs. That matters: several bugs found this way lived only in the formatting layer.

The page SyncTeX names is not always the page it is on

SyncTeX records the page a box was built on. A float that TeX moves to the next page gets the previous page's number, so text: "Version 0.5" used to answer "page 205" for a table that ships on 206 — and page 205 is a different chapter. The tool now checks the PDF's own text layer (gs -sDEVICE=txtwrite, ~0.12 s a page) and looks one and two pages either side; when it overrules SyncTeX it says so.

One picture, not two

A compare call writes three images, but the one to show the user is images.sideBySide: the page before on the left, the page after on the right, one PNG. Finding the difference by eye across two separate files is the hardest part of the job for someone who cannot read the source.

Writing a PNG needs no dependency — a signature, IHDR, one zlib IDAT, IEND, and node:zlib supplies the compression. The composite costs about 0.3 s on an A4 page at 140 dpi, and only runs when there is something to compare.

Performance

Verifying an edit always costs a real compile; there is no way around that. But browsing pages of the same build should not:

A build is reused when the document, everything it \input/\includes (three levels), its \includegraphics files and its aux files are unchanged (mtime and size). A failing build is never reused. Pass fresh: true to bypass it.

Two consequences worth knowing:

• The before-snapshot belongs to the build, not to the call. After an edit, the first look records what the page looked like before it; every later look at that same build reuses the same snapshot, so an agent inspecting three pages of its own edit still sees a diff on the second and third. (It used to be consumed by