`latex_it` Technical Reference for LLMs & AI Agents

Audience: Autonomous coding agents (Claude Code, Antigravity, Cursor, OpenCode, Aider) and programmatic pipelines.
Purpose: Dense, token-optimized technical reference covering CLI flags, configuration schemas, exit codes, and diagnostic contracts. Zero prose filler.

1. Quick Execution Contract

When compiling LaTeX documents in a repository where latex_it (or l) is available:

# Recommended compile invocation for all AI agents:
l -llm paper.tex

# With all folded warnings displayed:
l -llm -a paper.tex

# Programmatic JSON response:
l --json paper.tex

Exit Codes

2. Core Architectural Invariants

Junk Quarantine: All compilation artifacts (.aux, .log, .toc, .fls, .out, .nav, .snm) reside exclusively in junk/. Only <file>.pdf, <file>.bbl, and <file>.synctex.gz are written to root.
Engine Selection Precedence: CLI flag (-e) / symlink personality (llua, lp) $>$ % !TEX program = <engine> magic comment $>$ .l.jsonc "engine" $>$ default (xelatex).
Convergence Loop: Multi-pass scheduler runs up to passes (default 3). Exits early if .aux digests match across passes. Executes BibTeX/Biber if citations are unresolved or .bib files modified.
Cache State: Persisted in junk/.build_state.json. If inputs (*.tex, *.bib, styles) and CLI options match SHA256 hashes, exits 0 in 0 passes.

3. Comprehensive CLI Options Reference

Flag	Long Form	Value Type	Default	Description
`-llm`	`--agent`	flag	`false`	Primary agent profile: Pure plaintext, folded warnings, silent on clean success.
`--json`	(none)	flag	`false`	Emit structured JSON result payload on stdout.
`-f`	`--force`	flag	`false`	Force initial LaTeX run unconditionally (bypasses build cache).
`-u`	`--single-pass`	flag	`false`	Execute exactly 1 LaTeX pass without BibTeX/Biber or convergence passes.
`-n`	`--passes`	integer (1–3)	`3`	Maximum number of LaTeX compilation passes.
`-b`	`--[no-]bib`	boolean	auto	Force or skip bibliography pass (Biber or BibTeX).
`-I`	`--[no-]index`	boolean	`false`	Run `makeindex` when `.idx` changes.
`-e`	`--engine`	`x`,`l`,`p`	`x` (`xelatex`)	Compiler: `x` (`xelatex`), `l` (`lualatex`), `p` (`pdflatex`).
`-c`	`--clean`	flag	`false`	Remove `junk/` artifacts before starting build.
`-C`	`--clean-only`	flag	`false`	Remove `junk/` and root auxiliary files and exit immediately.
(none)	`--junk-dir`	string	`junk`	Directory for temporary build artifacts (`junk` or `.junk`).
`-x`	`--explain`	flag	`false`	Print boxed plain-English explanations on first diagnostic occurrence.
`-a`	`--all`	flag	`false`	Display all diagnostics (disables warning folding and whatever suppression).
`-W`	`--werror`	flag	`false`	Treat alerts and warnings as fatal errors (exit code 1).
`-r`	`--raw`	flag	`false`	Print unfiltered raw stdout/stderr from TeX compilers.
`-s`	`--score`	flag	`false`	Suppress stdout; print numeric diagnostic counts only.
`-v`	`--verbose`	flag	`false`	Verbose logging; show raw overfull snippets.
`-T`	`--time`	flag	`false`	Print wall-clock execution time per pass.
`-m`	`--main`	flag	`false`	Print detected root `.tex` filename and exit.
`-M`	`--deps`	flag	`false`	Output Makefile dependency rule for document and exit.
`-z`	`--zip`	flag	`false`	Create self-contained portable zip archive of paper, styles, and figures.
`-Z`	`--zip-flat`	flag	`false`	Create portable zip with flattened/inlined `.tex` source.
`-t`	`--verify`	flag	`false`	Test portable zip in isolated `/tmp` sandbox with clean environment.
`-B`	`--bib-extract`	flag	`false`	Extract cited references into local standalone `.bib` file.
`--arxiv`	(none)	flag	`false`	Produce submission-ready, comment-stripped arXiv archive.
`--meta`	(none)	flag	`false`	Extract sanitized metadata and write `arxiv_<file>_meta.txt`.
`--update-if-changed`	flag	`false`	Skip overwriting target PDF if extracted text is unchanged (`pdftotext`).
`--no-env`	(none)	flag	`false`	Clear ambient `TEXINPUTS`, `BIBINPUTS`, and `TEXMFHOME`.
`--[no-]lock`	boolean	`true`	File locking concurrency protection (`flock`).
`--[no-]color`	boolean	auto	Terminal ANSI color escape sequences.
`--[no-]link`	boolean	auto	Terminal OSC 8 clickable hyperlinks.
`--alert-hbox`	float (pt)	`24.0`	Overfull `\hbox` size in pt promoted to Alert.
`--whatever-pt`	float (pt)	`2.5`	Overfull `\hbox` size in pt demoted to Whatever (suppressed).
`-cc`	`--compile`	flag	`false`	GNU standard compiler output (`file:line:col: severity: msg`).
(none)	`--gitignore-init`	flag	`false`	Additive setup: create or add standard LaTeX & `junk/` rules to `.gitignore`.

4. Configuration Schema (`.l.jsonc`)

Local file: ./.l.jsonc (or ./.latex_it.jsonc).
Global file: ~/.config/latex_it/config.jsonc.

{
  "engine": "xelatex",               // "xelatex" | "lualatex" | "pdflatex"
  "passes": 3,                       // 1 | 2 | 3
  "junk_dir": "junk",                // "junk" | ".junk" (build artifact directory)
  "index": false,                    // boolean (makeindex)
  "update_on_diff": false,           // boolean (suppress PDF write if text unchanged)
  "time": false,                     // boolean (timing diagnostics)
  "raw": false,                      // boolean (unfiltered engine output)
  "trace": false,                    // boolean (log subprocess commands)
  "color": null,                     // true | false | null (auto)
  "links": null,                     // true | false | null (auto OSC 8 links)
  "theme": "blush",                  // "blush" | "catppuccin" | "tokyo-night" | "dracula" | "nord" | "ansi"
  "lock": true,                      // boolean (flock concurrency guard)
  "werror": false,                   // boolean (warnings are fatal)
  "alert_overfull_pt": 24.0,         // float (threshold for Alert tier)
  "whatever_overfull_pt": 2.5,       // float (threshold for Whatever tier)
  "suppress_whatevers": true,        // boolean (hide micro-noise)
  "suppress_warnings": false,        // boolean (hide standard warnings)
  "suppress_alerts": false,          // boolean (hide structural alerts)
  "bib_dirs": ["refs", "bib"],       // string[] (directories to scan for .bib files)
  "junk_subdirs": ["figs"],          // string[] (subdirs to pre-create in junk_dir)
  "auto_mirror_subdirs": true,       // boolean (mirror project subdirs into junk_dir)
  "exclude_main_tex": ["preamble*"], // string[] (globs ignored for main file detection)
  "exclude_source_tex": ["styles/*"] // string[] (globs ignored for brace/syntax audit)
}

5. Diagnostic Severity Tiers

Tier	Severity Label	Definition & Examples	Default Behavior in `-llm`
Errors	`error:`	Hard compilation crashes preventing PDF output. Syntax errors, missing packages, undefined control sequences.	Emitted first (max 5 errors displayed). Suppresses all lower tiers.
Alerts	`warning: [alert]`	Silent flaws that compile with exit code 0 but corrupt document semantics. Inverted `\label` before `\caption`, overfull `\hbox` $\ge 24\text{pt}$, duplicate labels, Type 3 raster fonts.	Displayed in plaintext. Counted towards `-W` fatal errors.
Warnings	`warning:`	Standard typesetting notices. Undefined citations, undefined `\ref`, overfull `\hbox` ($2.5\text{pt} < \text{pt} < 24\text{pt}$).	Folded: top 2 instances displayed + summary count note.
Whatevers	`note:`	Harmless cosmetic noise. Micro-overfull `\hbox` ($\le 2.5\text{pt}$), `hyperref` bookmark math removals, font substitutions.	Suppressed by default. Shown only with `-a`.

6. Behavior of `-llm` Mode

Zero ANSI / OSC 8: Guaranteed plaintext. No \e[ sequences, no OSC 8 hyperlinks \e]8;;.
Silence on Clean Success: If exit code is 0 and no actionable alerts/warnings exist, output is 0 bytes.

Category Folding: Undefined citations, references, and overfull boxes show at most 2 instances:

paper.tex:12: warning: [alert] undefined citation 'knuth1984'
paper.tex:15: warning: [alert] undefined citation 'lamport1994'
latex_it: note: 48 more undefined citations in paper.tex (pass -a to show all)

Log-Tail Fallback on Crash: If engine exits non-zero without a standard regex match:

paper.tex:1: error: compilation failed with unclassified error
paper.tex:1: note: compiler log tail:
> ! Emergency stop.
> <read 2> \relax
> l.42 \include{missing}

7. `--json` Schema Specification

{
  "success": false,
  "exit_code": 1,
  "pdf_path": null,
  "summary": {
    "errors": 1,
    "alerts": 0,
    "warnings": 2,
    "whatevers": 0
  },
  "diagnostics": [
    {
      "file": "paper.tex",
      "line": 42,
      "col": 1,
      "tier": "errors",
      "category": "undefined_control_sequence",
      "message": "undefined control sequence \\myTypo",
      "token": "\\myTypo",
      "hint": "did you mean \\myType?",
      "index": 0,
      "repeat_count": 1
    }
  ],
  "folded_counts": {},
  "log_tail": null
}

8. Common LaTeX Errors & Agent Remediations

Error Pattern	Root Cause	Agent Remediation
`undefined control sequence \foo`	Typo in macro or missing package.	Verify spelling; check if `\usepackage{...}` is required in preamble.
`Inverted \label before \caption`	`\label` placed before `\caption`.	Move `\label{...}` to immediately after `\caption{...}` inside float.
`Missing $ inserted`	Math symbol (`_`, `^`, `\alpha`) in text mode.	Wrap symbol in $ ... $ or escape (`\_`).
`File ended while scanning use of`	Unclosed brace `{` or environment argument.	Check line for missing closing brace `}`.
`\begin{env} ended by \end{other}`	Mismatched environment tags.	Ensure `\begin{foo}` matches `\end{foo}`.
`Package biblatex Error: File ... not found`	Missing compiled `.bbl` or backend mismatch.	Run `l -f` to force rebuild; verify `bib_dirs` in `.l.jsonc`.
`Token not allowed in a PDF string`	Math or formatting macro inside `\section{...}`.	Use `\texorpdfstring{$O(n)$}{O(n)}` in section title.
`Overfull \hbox ... (>= 24pt)`	Line extends >8.5mm past page margin.	Add discretionary hyphen `\-` or wrap offending text in `sloppypar`.

latex_it Technical Reference for LLMs & AI Agents