TeXButler (LaTeX Butler)

English | 简体中文

A local LaTeX compiler with an AI assistant, built for Chinese academic and report writing. It works out of the box — you don't need to install TeX Live to compile PDFs.

Highlights

1. Self-contained local compilation — bundles the Tectonic 0.15 engine, so it compiles Chinese LaTeX to PDF even without TeX Live; automatically falls back to a system xelatex/lualatex when detected.
2. AI error diagnosis & repair — turns cryptic LaTeX errors into plain language with the real error line; one-click fix: deterministic fixes (missing packages / undefined commands / missing \end{document}) → AI diff → audit (referenced-file existence check) → apply → recompile, with automatic rollback on failure.
3. Chinese-LaTeX specific checks — 10 rules (bare %, \textit with CJK, [ht] float drift, floating-point garbage, glued paragraphs, dangling refs/cites, …) that run automatically on save.
4. Made for writing (v0.2.0) — one-click image insertion with generated code, quick-format buttons (sections / formulas / tables / lists), AI code generation from natural language, Word (.docx) import → AI generates a complete compilable LaTeX document, user template library, math-symbol panel (36 symbols), day/night theme, and a bilingual UI (中文 / English).
5. Smooth writing flow (v0.3.0) — drag images into the editor or paste screenshots (auto-saved, insert dialog with width/position/caption), an Outline panel (section tree, click to jump), a Bibliography panel (click a .bib entry to insert \cite), LaTeX autocompletion (60+ commands, environment pairs), optional auto-compile after save, session restore on startup, and Ctrl+P quick file open.
6. End-to-end verifiable — real-API + real-compile e2e tests (cargo test --test e2e_ai -- --ignored) validate every layer of the fix loop.
7. Liquid Glass UI (v0.4.0) — default glassmorphism theme: animated gradient light blobs behind frosted-glass panels with specular highlights; three themes (liquid glass / classic dark / classic light) switchable from the toolbar and persisted; the Monaco editor theme follows. Monaco is bundled locally — fully offline, no CDN. Always-visible quick math symbols (α β γ δ θ λ π √ ∫ ∞ ± ≤) plus a 90-symbol panel.
8. Dangling-ref rule + smart completions (v0.5.0) — rule #10 checks every \ref against the project's \labels and every \cite against the .bib keys before you compile; \ref{ / \cite{ autocomplete from the live project index. Word count (comments/commands excluded) in the status bar; visual booktabs table generator; AI translate that preserves the LaTeX structure; SyncTeX forward search ("locate in PDF"); multi-document compile targets; LaTeX → Markdown/Word export; debounced save-triggered auto compile.
9. AI co-editing (v0.6.0) — chat with the AI and it edits your files: ask in plain language ("change the title to…", "add a page break before every question") and the AI replies with declarative tool calls (insert / replace / delete) that the program executes precisely — batched, with automatic retry, no fragile diff parsing. Every edit is snapshotted first and lands in the editor and PDF preview instantly (compile-verify loop: the AI recompiles after each change and self-heals one round on failure). The AI knows your document (class, packages, CJK support, compiler engine), remembers the conversation, and never clobbers unsaved typing. The panel is a collapsible right-side rail (34px strip when closed), with streaming replies, selection-based questions, session token usage with cost estimate, and a per-project AI_GUIDE.md style guide injected into every AI prompt.
10. Template marketplace & file workflows (v0.7.0) — 160+ verified templates covering domestic 985/211 universities, overseas QS top-100, journals, slides, posters, resumes, letters, reports and coursework; 8 built-in templates are compile-verified at build time and downloads pass a structure check (\documentclass root detection) before use. New files are created in the current directory with a template picker (article / ctexart / report / beamer / minimal / blank); templates can also be imported safely into an open project with conflict detection, rollback and cleanup. AI conversations are persisted per project file and auto-switch with the editor tab; the AI panel layout is rebuilt (messages, input and tool menus never overlap), editor tools collapse into an overflow menu on narrow windows, and every panel separator bar drags reliably.
11. Welcome screen & project dashboard (v0.7.0) — a welcome screen lists recently opened projects for one-click restore (failed opens are cleaned up automatically); the status bar shows cumulative compile count and word history per project.
12. Workspace tools (v0.8.0) — file management in the tree (new folder, rename, move, drag & drop, delete with undo), project-wide search & replace (case / whole word / regex), a built-in pdf.js viewer that keeps your place across recompiles with forward highlight and double-click reverse SyncTeX, local file history with diffs and restore, Git status badges, a reference report (undefined / duplicate / unused labels, citation counts, missing citations), offline English spell check, editor preferences, one-click verified Tectonic install, an in-app updater, AI "fix all errors" and image → formula. The UI follows Apple's Human Interface Guidelines, and the liquid-glass theme now uses an Apple Liquid Glass look.
13. Writing tools (v0.9.0) — rename a \label or citation key with F2 and every \ref / \cite (and the .bib entry) follows across the project; GBK-encoded files open correctly and convert to UTF-8 in one click; bibliography checks for author separators, DOI prefixes, missing fields and GB/T 7714 requirements (publisher place, volume/issue, pages, access dates); cite straight from Zotero through Better BibTeX, with missing entries appended to the .bib; and an AI full-document review that lists findings you accept or dismiss one by one.

Tech Stack

Layer	Technology
Desktop	Tauri 2 (Rust backend + WebView2 frontend)
Frontend	React 18 + TypeScript + Vite + Monaco Editor + zustand
Compile engine	Tectonic 0.15 (bundled binary, on-demand bundle cache / offline) + system TeX Live / MiKTeX fallback
AI layer	Rust HTTP client, multi-provider (OpenAI-compatible / Anthropic / Ollama)

Note: the Tectonic driver uses the official prebuilt binary (src-tauri/resources/bin/tectonic.exe) instead of the tectonic crate, because the crate's tectonic_bridge_png build script requires a system libpng (pkg-config/vcpkg only) — which conflicts with "install & run on a clean machine". See docs/ARCHITECTURE.md.

Development Setup

Prerequisites:

• Rust (stable, MSVC toolchain)
• Node.js ≥ 18
• Windows 10/11 (WebView2 included on Win11)
• Optional: TeX Live / MiKTeX (system-engine fallback; Tectonic works without it)

# 1. install frontend deps
npm install

# 2. dev mode (hot reload, auto-launches the window)
npm run tauri dev

# 3. unit tests (Rust core)
cargo test

# 4. end-to-end tests (real API + real compile; requires an AI API key)
cargo test --test e2e_ai -- --ignored --nocapture

# 5. build installers (NSIS + MSI)
npm run tauri build

On the first compile, Tectonic downloads resources on demand from https://relay.fullyjustified.net into a local cache (tens of MB); afterwards it compiles offline. You can pre-warm it via Settings → "Pre-download Tectonic bundle".

Quick Start

1. Click Open to select any folder containing .tex files (or New with a template: article / report / slides / your saved templates);
2. Open main.tex in the file tree and edit (Ctrl+S saves & triggers rule checks; Ctrl+B compiles, Ctrl+Shift+B compiles the current file; right-click a .tex file to set it as main);
3. Click ▶ Compile → PDF preview on the right; the "Compile errors" panel lists errors with real line numbers (click to jump); the "Log" button shows the raw main.log;
4. Select an error → AI explain (plain-Chinese explanation + fix advice) or AI fix (deterministic fix → AI diff → audit → apply → recompile → auto-rollback);
5. The "Rule check" tab shows the 10 Chinese-LaTeX rule hits (with fix hints and one-click deterministic fixes), toggleable in Settings;
6. The status bar shows engine / duration / issue count; Settings shows system-font detection and bundle status.

v0.2.0 writing aids

• Insert image: click the image button in the editor toolbar, pick an image — it is copied into the project and a figure/includegraphics block is inserted at the cursor.
• Quick formats: toolbar buttons for paragraph / section / bold / inline & display math / lists / tables.
• AI generate: type a request in the AI panel (e.g. "generate a three-line booktabs table") → the AI writes the code straight into your file (or returns it as a reply), with one-click rollback.
• Word import: toolbar Word→LaTeX → pick a .docx → headings/paragraphs/tables are parsed and AI generates a complete compilable LaTeX document.
• Templates: the star button in the project tree saves the current project as a reusable template; the new-project dialog lists built-in + user templates (user ones can be deleted).
• Math symbols: the αβ button opens a 36-symbol panel (α β γ … ∑ ∫ √ ± ≤ ≥ ≈ ≠ ∈ ∀ ∃) — click to type, no need to memorize commands.
• Day/night theme: day/night toolbar toggle, persisted across restarts.

Demo Project

assets/demo-project/ contains a project with seeded errors (missing xcolor, undefined command, 71%, Chinese italics, [ht], floating-point garbage) — a quick way to try the AI fix loop.

Directory Layout

├── src/                  # frontend (React + TS)
│   ├── api/              # typed invoke wrappers (tb_* commands)
│   ├── store/            # zustand stores
│   ├── i18n/             # zh/en dictionaries
│   └── components/       # tree / editor / PDF / problems / AI / settings
├── src-tauri/
│   ├── src/
│   │   ├── commands/     # Tauri commands
│   │   └── core/         # core logic (compiler / rules / ai / log_parser …)
│   └── resources/bin/    # bundled tectonic.exe
├── assets/sample/        # Chinese regression sample
├── assets/demo-project/  # demo project with seeded errors
├── assets/screenshot-project/ # showcase project used for the README screenshot
├── assets/e2e/           # e2e fixture projects
└── docs/                 # ARCHITECTURE.md / PLAN.md

Rule Engine (10 rules)

ID	Rule	Level
percent	bare % mistaken for a comment (71% )	suggestion
italic	\textit/\emph wrapping CJK (no italic CJK fonts)	warning
bold	& inside \textbf (triggers "File ended…")	warning
float	[ht] placement drift → prefer [H] + float package	info
color	blue!60 mixing without xcolor	error
numbers	floating-point garbage (87.30000000000001)	error
paragraph	adjacent prose lines without a blank line	info
missing_end	\begin{document} without \end{document}	error
bom	UTF-8 BOM header	warning

The registry is extensible: add a file under src-tauri/src/core/rules/ and register it in all_rules(). Most hits offer a one-click deterministic fix (e.g. glued paragraphs are repaired in batch without AI).

AI Fix Loop (architecture)

1. Deterministic fixes (no AI): missing xcolor → add \usepackage{xcolor}; standalone undefined command → delete exactly the compiler-reported line; missing \end{document} → append; glued-paragraph batches (one click fixes them all, no AI needed).
2. AI diff generation: project file inventory injected (the AI must never reference non-existent files) + full numbered source on later rounds (prevents line-number hallucination) + per-error-type handling rules.
3. Diff audit: referenced-file existence check, content-based hunk location for line-number drift, ambiguity rejection, no-op pair cleanup, *** End of diff trailing-marker tolerance.
4. Progressive verification: track the currently failing error, keep applied fixes, real compile after every round, ≤3 rounds, automatic rollback to the original (snapshots in .texbutler/backup/).

Conversational edits (tool-call channel)

AI replies in the chat panel use the same hardened pipeline through declarative tool calls instead of free-form diffs: insert_before / insert_after / replace / delete_line with anchor-text matching (unique-match enforced, line numbers optional). The program executes them deterministically — a batch of calls applies atomically per file, each file gets its own snapshot and rollback entry, and a failed apply automatically retries once with the fresh file content. Free-form diffs remain as a fallback. After every edit the AI recompiles; on failure the errors feed back for one self-healing round, and the result (editor + PDF preview + diagnostics) syncs automatically — except into tabs you are actively typing in.

AI Configuration

Settings support three providers (base_url / model / key persisted to %APPDATA%\texbutler\settings.json):

• OpenAI-compatible: OpenAI / DeepSeek / Qwen (DashScope)
• Anthropic: native Messages API
• Ollama (local): http://localhost:11434/v1 OpenAI-compatible endpoint, no key needed

2026-08 model presets: GPT-5.6 Luna/Terra, DeepSeek V4 Flash/Pro, Qwen3.7-Plus, Claude Sonnet-5/Haiku-4.5, Ollama Qwen3.5.

Security: AI requests only receive the error snippet + a local context window (20 lines around; the full file on later rounds), never other files; the API key is stored locally and never logged; fixes always preview the diff first and every write is snapshotted for rollback. Edits are limited to a .tex/.bib/.sty/.cls allowlist (AI_GUIDE.md and .texbutler are protected), paths are normalized against traversal, and guide injections ignore behavior-directive attempts.

License

MIT License © 2026 WhitePepperLambSoup (苏喆) (see LICENSE). Note: the MIT license requires retaining the copyright notice — keep the LICENSE file and the copyright line when distributing or modifying this project.