lsp-setup — texlab integration for Claude Code

The plugin already ships a .lsp.json at its root with sensible defaults (latexmk-driven build, 300ms diagnostics delay, restart-on-crash). This skill explains how to verify, tune, and troubleshoot.

Verify texlab is installed

command -v texlab && texlab --version

Expected output: a path and a version like texlab 5.x.x. If missing, install:

Note: do NOT cargo install texlab from crates.io — versions there are no longer kept current.

What the plugin's .lsp.json provides

The shipped default (at <plugin-root>/.lsp.json):

{
  "texlab": {
    "command": "texlab",
    "extensionToLanguage": {
      ".tex": "latex", ".ltx": "latex", ".sty": "latex",
      ".cls": "latex", ".dtx": "latex", ".bib": "bibtex"
    },
    "settings": {
      "texlab": {
        "build": {
          "executable": "latexmk",
          "args": ["-pdf", "-interaction=nonstopmode", "-synctex=1",
                   "-file-line-error", "-halt-on-error", "%f"],
          "onSave": false,
          "forwardSearchAfter": false
        },
        "diagnosticsDelay": 300,
        "chktex": { "onOpenAndSave": false, "onEdit": false }
      }
    },
    "startupTimeout": 10000,
    "restartOnCrash": true,
    "maxRestarts": 3
  }
}

Source for fields: https://github.com/latex-lsp/texlab/wiki/Configuration.

Tuning recipes

Switch default build engine to xelatex or lualatex

Edit settings.texlab.build.args:

"args": ["-pdfxe", "-interaction=nonstopmode", "-synctex=1",
         "-file-line-error", "-halt-on-error", "%f"]

Replace -pdfxe with -pdflua for LuaLaTeX.

Enable build-on-save

"build": { "onSave": true, ... }

Saves trigger latexmk automatically. Convenient but slows perceived save speed; off by default.

Enable chktex on save

"chktex": { "onOpenAndSave": true, "onEdit": false }

Adds chktex's stylistic warnings (Wrong length of dash, \: should be inserted before, etc.). Default is off because chktex is opinionated.

Forward search (PDF viewer ↔ source jump)

"forwardSearch": {
  "executable": "<viewer-binary>",
  "args": ["<viewer-args-with-placeholders>"]
}

Examples:

Placeholders: %f = source file, %p = PDF, %l = line.

Tune diagnostics

"diagnostics": {
  "allowedPatterns": ["^!", "^l\\.[0-9]+", "Reference .+ undefined", "Citation .+ undefined"],
  "ignoredPatterns": ["^Overfull \\\\hbox.*"]
}

Reduce noise; promote specific signals.

Custom label commands (extend cross-reference tracking)

If your project defines custom theorem/figure environments not detected by default:

"experimental": {
  "labelDefinitionCommands": ["mytheorem"],
  "labelReferenceCommands": ["mycref"],
  "labelDefinitionPrefixes": [["mytheorem", "thm"]]
}

Per-project override

If a single project needs different settings than the plugin defaults, create .claude/settings.local.json in the project:

{
  "lspServers": {
    "texlab": {
      "settings": { "texlab": { "build": { "args": [...] } } }
    }
  }
}

Project settings merge over plugin defaults. Per-project tuning beats editing the plugin.

Troubleshooting

Executable not found in $PATH

Plugin loaded but texlab binary isn't on PATH. Install (see above), then /reload-plugins or restart Claude Code.

Diagnostics don't update

• Check texlab.diagnosticsDelay isn't set absurdly high.
• texlab requires a successful build to derive some diagnostics. Run a manual latexmk and confirm the .log is fresh.
• For chktex-style warnings, set chktex.onEdit: true.

Stale cross-file references

texlab walks \input/\include and .aux data. If references break across files:

• Compile once so .aux is fresh.
• Make sure all source files are inside the workspace root.
• Restart the LSP: in Claude Code's /plugin UI, disable then re-enable the plugin.

Build timeout

Increase the LSP startup timeout:

"startupTimeout": 30000

A first-run latexmk on a large document can take longer than the 10s default.

Sanity check

Open a .tex file in Claude Code. Confirm via the LSP tool that texlab is the active language server. Editing should produce diagnostics within ~300ms; hovering a \ref{key} should show the labeled environment.

When uncertain

For texlab-specific options not covered here, the canonical reference is the texlab wiki: https://github.com/latex-lsp/texlab/wiki/Configuration. For LSP integration questions specific to Claude Code, see https://code.claude.com/docs/en/plugins-reference#lsp-servers.

When in doubt about a setting's effect, delegate to /academic-latex:docs-lookup with the wiki URL.

Last verified

2026-05-09 — texlab GitHub repo, wiki, and code.claude.com plugins-reference §LSP.