MagicTeX

MagicTeX — AI エージェント向け LaTeX エディター

English · 简体中文 · 日本語 · 한국어 · Español · Français · Deutsch · Português

MagicTeX は、AI エージェント向けに構築された LaTeX エディターです。Claude Code 向けの Overleaf のような単一ウィンドウのワークスペースで、MCP サーバー経由で提供されます。ローカルへの TeX のインストールも、Overleaf アカウントも不要です。ライブ PDF プレビュー、Visual（WYSIWYG）モードを備えたソースエディター、変更履歴に加え、レンダリングされた PDF 上に固定したコメントを、エージェントへの編集指示として利用できます。（npm パッケージ：magictex-mcp。）

ヘッドレスブラウザー内で動作する WASM TeX Live 2026 エンジン（texlyre-busytex）を使用してコンパイルするため、ギガバイト単位のものをインストールする必要はありません。必要なのは、WASM アセットの初回ダウンロードだけです。

インストール前に確認する

コメントからエージェントまでの一連の流れを案内するウォークスルーは、実際のツール出力をもとに作成された zoelin.dev/tools/magictex でご覧いただけます。これはリプレイであり、ホストされたインスタンスではありません。TeX エンジンの初回ダウンロードには約 650 MB 必要で、エージェント側は Claude 自身が担うため、MagicTeX はウェブページ上ではなく、プロジェクトのそばで動作します。

ワークスペース

Typst のワン画面エディターと LiquidText のアンカー付き注釈に着想を得た、1 つのブラウザーウィンドウです。

┌──────────────────────────────────────────────────────────────┐
│  ✓ up to date · 13 pages        Export .zip · Download PDF   │
├────────────┬──────────────────────────────┬──────────────────┤
│ Source /   │          PDF (live)          │    Comments      │
│ History    │  select text → 💬 comment    │  accepted → ask  │
│  editor,   │  highlights stay anchored    │  Claude to       │
│  timeline  │  auto-reloads on every edit  │  address them    │
│  + diffs   │                              │  → resolved ✓    │
└────────────┴──────────────────────────────┴──────────────────┘

• コメント → Claude のループ（この機能の要です）。 印刷物に監修者が書き込むように、レンダリングされたドキュメントを確認します。テキストを選択して、コメント（「この段落を簡潔にする」など）を付けます。次に Claude に 「コメントに対応して」 と伝えると、Claude は check_comments を使って、位置情報付きの作業項目（ページ＋引用箇所＋アンカー先のソース file:line＋依頼内容）を取得し、ソースを編集して、各カードにメモを付けて解決します。あなたはドキュメントを操作し、Claude はソースを操作します。/loop を使えば手放しで実行できます。詳しくは docs/AGENT-LOOP.md をご覧ください。
• 編集可能なソースパネル。 プロジェクトのファイルを扱える CodeMirror LaTeX エディターです。保存（Ctrl+S）すると再コンパイルされ、Typst 形式で PDF が更新されます。自分のエディターを使い続けることもできます。どのエディターからの保存でも同じライブ処理が実行されます。
• ライブリロード。 ファイルウォッチャーが保存のたびに再コンパイルします。Claude の編集、組み込みエディターの編集、外部エディターの編集が対象です。
• 変更履歴。 コンパイルが成功するたびに、非表示の git ref（refs/latex-preview/checkpoints）へスナップショットが自動保存されます。ブランチ、git log、作業ツリーには一切触れません。History タブではタイムラインと各チェックポイントの色分けされた差分を PDF の横に表示します。
• Overleaf に移行。 PDF をダウンロード、.zip をエクスポート（ビルド入力をまとめたクリーンなバンドル）、公開 GitHub リポジトリ用のワンクリック Overleaf で開くリンクを利用できます。Premium の Git ブリッジ同期には、ドキュメントに記載された git push を使います。詳しくは docs/USER-GUIDE.md をご覧ください。
• レビューのワークフロー（レビュアー → ゲート → 解決担当者）。 レビュアー／ディフェンダーエージェントが add_comment でコメントを投稿します。あなたがコメントを承認／却下するか、コパイロットモード用に 自動承認 を切り替えると、作成者のループが承認済みコメントを解決します。コメントにはロールと返信スレッドが含まれます。詳しくは docs/AGENT-LOOP.md をご覧ください。
• 保存と再コンパイルを使い分けられます。 組み込みエディターは再コンパイルせず、30 秒ごとに自動保存します。Ctrl+S／保存／再コンパイルを実行すると、必要に応じて PDF を再ビルドします。（入力中に再コンパイルするには ⚡ ライブ を切り替えます。）自分のエディターや Claude による編集は、引き続きウォッチャーによって自動再コンパイルされます。
• 実際のプロジェクトに対応。 メインファイルを自動検出し、複数ファイルの \input／\include、.bib、リポジトリ内の .cls／.sty／.bst、図を収集します。BibTeX を実行し、必要に応じて再実行します。よく使われる不足パッケージは自動で追加されます。
• コンパイルバックエンド。 ローカルに latexmk がある場合はそれを使います。パッケージへの完全な対応により、Overleaf と同等の出力が得られます。ない場合は、インストール不要で同梱された WASM TeX Live を使います。backend: "system"／"wasm" を指定して、どちらかを強制的に使うこともできます。各コンパイルでは、実行されたバックエンドが報告されます。
• ドキュメントクラス。 IEEEtran は同梱されています。WASM TeX Live には投稿先のクラスが含まれず、パッケージのように不足したクラスを回避する方法もないためです。会議用クラス（NeurIPS、ICML、CVPR、ACL、AAAI など）は再配布可能なライセンスがないため、著者キットの .cls をソースと同じ場所に置いてください。自動的に認識されます。
• MCP ツール： render_preview（コンパイルしてワークスペースを開く）、check_comments／resolve_comment／add_comment／reply_to_comment（レビューのループ）、show_diff（画像として並べて表示する差分。画像対応クライアントで便利です）。
• 対処可能なエラー。 コンパイルに失敗すると、解析済みの {file, line, message} エラーが返されるため、Claude が自分で修正できます。エラーはワークスペースにも表示されます。

セットアップ

MagicTeX は npm の magictex-mcp として公開されており、 公式 MCP レジストリには **io.github.ZoeLinUTS/magictex**として登録されています。そのため、レジストリを参照するクライアントならどれでも見つけられます。 クローンも TeX のインストールも不要です。初回の使用時に npx が取得します。

1. 論文プロジェクトの .mcp.json に追加します（.mcp.json.exampleを参照）：

   {
     "mcpServers": {
       "magictex": { "command": "npx", "args": ["-y", "magictex-mcp"] }
     }
   }
   

   クローンからローカル開発する場合は、代わりにソースを指定してください： "command": "npx", "args": ["tsx", "/absolute/path/to/magictex-mcp/src/server.ts"]

2. サーバーを読み込ませるため、Claude Code を再起動します（または /mcp で再接続します）。

3. Claude にレンダリングを依頼します。 例：「この論文のプレビューをレンダリングして」 → 初回の呼び出しで WASM TeX Live アセット（約 650 MB、一度のみ）をダウンロードし、コンパイルして、ライブプレビューのタブを開きます。以降の編集は自動的に再読み込みされます。

WASM アセットはこのリポジトリには含まれていません。初回実行時にユーザーごとのキャッシュ（macOS では ~/Library/Caches/magictex、Linux では $XDG_CACHE_HOME/magictex、Windows では %LOCALAPPDATA%\magictex）へ取得されます。そのため、MagicTeX をアップグレードしても再ダウンロードされず、チェックアウト、グローバルインストール、npx の実行で同じコピーを共有できます。別の場所に保存するには MAGICTEX_ASSETS_DIR を設定してください。事前に取得するには： npx texlyre-busytex download-assets <that directory>。

Claude Code プラグインとしてインストール（スラッシュコマンド）

入力を減らしたワークフローにするには、MagicTeX をプラグインとしてインストールします。1 回のインストールで MCP サーバーとスラッシュコマンドの両方が使えるようになります：

/plugin marketplace add ZoeLinUTS/MagicTeX-mcp
/plugin install magictex

次に、論文プロジェクトで、よく使う作業にはワークフローコマンドを使います：

• /magic-latex — コンパイルしてワークスペース（ライブプレビュー）を開きます。
• /ai-review [skill] — スキルを使って論文をレビューし、承認／却下できるコメントを投稿します（デフォルトは academic-paper-revision。任意のスキル名を指定できます）。スキルが見つからない場合は、インストール方法のヒントを表示します。
• /address-comments — 承認したコメントに対応します（/loop 60s /address-comments で繰り返し実行できます）。
• ⚡ /ultra-agents [skill] [depth] — 全自動でレビュー、承認、修正を行い、最大 depth 回（デフォルトは 2 回）繰り返します。新たな指摘が見つからなかった時点で早期終了します。ラウンドごとの承認はありません。それがこのコマンドの特長であり、リスクでもあります。depth > 5 の場合は、開始前に確認を求めます。最後に、指摘内容、変更内容、確認すべきチェックポイントをまとめます。各ラウンドは通常の取り消し可能なチェックポイントとして残ります。docs/AGENT-LOOP.mdを参照してください。

ツールごとに1つのコマンド

すべての MCP ツールには、同じ名前のスラッシュコマンドもあるため、ツール名を入力すれば個別のステップを実行できます。覚えておくルールは、ツールが X なら /X を入力することです。

入力するコマンド	実行するツール	機能
/render_preview	render_preview	論文をコンパイルし、ライブプレビューを開く／更新します。
/check_comments	check_comments	編集指示として、承認済みのコメントを一覧表示します（まだ編集は行いません）。
/resolve_comment [id] [note]	resolve_comment	編集後にコメントを完了としてマークします。確認用に緑色になります。
/add_comment ["quote"] [note]	add_comment	あとで承認／却下できるよう、文章にコメントを追加します。
/reply_to_comment [id] [text]	reply_to_comment	コメントにスレッド形式で返信します。
/show_diff [checkpoint]	show_diff	現在の変更またはチェックポイントの、画像による左右比較の差分を表示します。
/list_checkpoints [limit]	list_checkpoints	新しい順に最近のチェックポイントとその sha を表示します。/show_diff に渡すものを探すときに使います。

これらを入力する必要はありません。普通の英語でも指示できます（「プレビューを表示して」、「コメントに対応して」）。これらのコマンドは、素早く実行できる覚えやすい省略形にすぎません。

このプラグインには MCP サーバー（npx magictex-mcp）が同梱されているため、プラグインをインストールするだけで使えます。上記の .mcp.json は、プラグインをインストールしたくない場合の代替手段です。どちらの場合もスラッシュコマンドを使えます。

ツール

MCP に対応するあらゆるクライアントで使える MCP のインターフェースです。（Claude Code では、普通の英語で依頼するか、上記のスラッシュコマンドを使えます。これらはその基盤となるツールです。）

ツール	パラメーター	機能
render_preview	mainFile? · engine?（pdflatex | xelatex | lualatex、デフォルトは xelatex）· backend?（wasm | system | auto、デフォルトは auto — インストール済みならローカルの latexmk、そうでなければ同梱の WASM エンジン）	プロジェクトをコンパイルし、ライブワークスペースを開く／更新します。省略した場合は、\documentclass を検索してメインファイルを自動検出します。
check_comments	includeResolved?（デフォルトは false）	承認済みのコメントを、ページ、引用箇所、ソースの file:line、依頼内容を含む、場所が特定された作業項目として返します。あなたの判断を待つレビュアーの提案も報告されますが、作業項目としては返されません。
add_comment	quote · comment · role?（reviewer | defender）· page? · accepted?	文章にコメントを追加します。accepted が設定されていない限り、承認／却下を待つ提案として投稿されます。このフラグによって自律モードが自律的に動作します。
resolve_comment	id · note	編集後に、変更点を説明する1行のメモを添えてコメントを完了としてマークします。ワークスペースでは、確認用に緑色になります。
reply_to_comment	id · text · role?（author | reviewer | defender）	スレッド形式で返信を追加します。意見の相違について、チャットではなくコメント上で話し合えます。
show_diff	checkpoint?	画像による左右比較の差分をレンダリングし、会話内に表示します。デフォルトでは、現在の未コミットの変更が対象です。保存済みバージョンを表示するには、チェックポイントの sha を渡します。
list_checkpoints	limit?（デフォルトは10、最大50）	新しい順に最近のチェックポイントとその sha を表示します。show_diff に渡すものを探すときに使います。

主要なワークフローはこれらの上に構築されており、これらの中には含まれません。 /magic-latex、 /ai-review、/address-comments、⚡ /ultra-agents は、上記のツールを連携させる Claude Code プラグインのコマンドです。/ultra-agents は、許可した回数だけレビュー → 自動承認 → 修正を繰り返します。このため、add_comment には accepted フラグがあります。これらは MCP のインターフェースには含まれないため、ほかの MCP クライアントから見えるのは7つのツールだけです。プラグインのセクションと docs/AGENT-LOOP.md を参照してください。

ターミナルで確認

以下は、サンプル論文に対して実際に実行した際のツール出力を、そのまま記録したものです。作り物ではありません。ブラウザのワークスペース（上のスクリーンショット）に同じ状態がリアルタイムで反映されている間、Claude Code で目にする内容です。

次のように入力します：

/magic-latex

Claude が render_preview を呼び出して返信します：

✓ Compiled main.tex with xelatex in 1900ms — 2 files. Workspace (live preview,
source editor, history, PDF comments — auto-reloads on edits):
http://127.0.0.1:52042/app

あなた（またはレビュースキル）がコメントを残し、対応可能な項目を尋ねます。Claude が check_comments を呼び出します：

1 accepted comment — edit each at its source location per the instruction, then
call resolve_comment with its id and a one-line note:

[id: 2fce9e3c8b5f] p.1 — "Sorting widgets efficiently is a long-standing problem"
  ↳ source: main.tex:15
  → Tighten this opening sentence.

(1 reviewer suggestion still awaits the human's accept in the workspace — not
actionable yet.)

Claude が編集を行い、resolve_comment を呼び出します：

✓ Resolved comment 2fce9e3c8b5f ("Sorting widgets efficiently is a long-standing
problem…") — the card now shows: Rewrote the opening sentence.

もう一度尋ねると、承認済みのキューは空になり、まだ承認されていない提案だけが 残り、あなたの対応を待っています：

No accepted comments. (2 already resolved.)

(1 reviewer suggestion still awaits the human's accept in the workspace — not
actionable yet.)

仕組み

Claude edits .tex ─┐
 file watcher ─────┼─▶ compile coordinator ─▶ headless Chromium ─▶ WASM TeX ─▶ PDF
 render_preview ───┘         (serialized)         (engine host)                │
                                                                               ▼
                     your workspace (/app)  ◀── WebSocket "reload" ◀── local HTTP server
                     Source · PDF · History · Comments        (serves /app + /latest.pdf)

WASM エンジンには DOM／Worker のグローバルが必要なため、サーバーはコンパイル用ワーカーとして 非表示のヘッドレス Chromium を起動します。あなたが開くワークスペースは、WASM を含まない軽量な React + pdf.js アプリです。docs/ARCHITECTURE.md をご覧ください。

flowchart LR
  H["👤 You<br/>Source · PDF · History · Comments"]
  A["🤖 Claude Code<br/>+ review / author agents"]

  H <-->|"select text →<br/>anchor comment"| SRV["Preview server<br/>HTTP + WebSocket · serves /app"]
  A -->|"7 MCP tools"| MCP["MCP server<br/>render_preview · show_diff · list_checkpoints<br/>check / resolve / add / reply_comment"]

  SRV --> CO["Compile coordinator<br/>(serialized)"]
  MCP --> CO
  A -. edits source .-> FILES[("Paper files · git repo")]
  FILES --> WATCH["File watcher"] --> CO
  CO --> ENG["WASM busytex<br/>(headless Chromium)"] --> PDF["/latest.pdf"]
  PDF -. live reload .-> H
  CO --> CK["git checkpoints<br/>(hidden ref) → History"]

  SRV <--> CJSON[(".latex-preview/<br/>comments.json")]
  MCP <--> CJSON
  CJSON -->|"check_comments<br/>(your accepted asks)"| A

2 つの入り口、つまりワークスペースを使うあなたと、7 つの MCP ツールを通じて操作するエージェントは、 同じコーディネーター、コメントストア、Git 履歴に接続します。あなたは レンダリングされたドキュメント に対して操作し（コメントのアンカーを設定）、Claude は ソース に対して操作します（check_comments であなたのコメントを読み取り、編集し、resolve_comment を実行します）。この共有基盤によって、コメントのやり取り、レビューのワークフロー、追跡可能な履歴が実現します。

要件

• Node 20.19+（chokidar と playwright が実際に必要とする最低バージョンです。サーバーは起動時にバージョンを確認し、必要なバージョンを知らせます）
• Playwright の Chromium（自動的にインストールされます。約 150～300 MB）—または、インストール済みの Chrome を再利用するように設定してください。
• WASM TeX Live アセットの初回ダウンロード用に約 650 MB のディスク容量。初回実行時にすべてダウンロードされ、3 つのパッケージセット（basic 87 MB、recommended 190 MB、extra 324 MB、およびエンジン 31 MB）で構成されます。通常の論文で 読み込まれる のは basic セットだけです。残り 2 つは、必要になるまでディスク上に置かれます。インストールごとではなくユーザーごとにキャッシュされるため、MagicTeX をアップグレードしても再ダウンロードされません。保存場所は MAGICTEX_ASSETS_DIR で変更できます。
• ローカルの TeX インストールは任意です。 必要になるケースについては、以下をご覧ください。

ローカルの TeX ディストリビューションは必要ですか？

いいえ。バンドルされた WASM エンジンは、何もインストールされていない環境でコンパイルできます。それが本来の目的です。ただし、収録されているのは TeX Live の 一部 なので、含まれていないものもあります。たとえば、svg、多くの投稿先のドキュメントクラス、あまり一般的でない各種パッケージなどです。必要なものが見つからない場合は、間違った PDF を黙って出力するのではなく、その旨が通知されます。

Overleaf とまったく同じ出力が必要な場合は、ディストリビューションをインストールしてください。 MagicTeX が自動で検出するため、設定は不要です：

macOS	MacTeX
Linux	パッケージマネージャーから texlive-full
Windows	TeX Live、または MiKTeX と Strawberry Perl

MagicTeX が PATH 上で探すのは latexmk ですが、単独でインストールするものではありません。上記のディストリビューションに含まれるドライバースクリプトです。which latexmk ではなく、latexmk -version で確認してください。latexmk は Perl スクリプトですが、MiKTeX は実行に必要な Perl を同梱せずに latexmk.exe を PATH に追加するため、ファイルは見つかっても実行できないことがあります。macOS では、先に eval "$(/usr/libexec/path_helper)" を実行するか、新しいターミナルを開く必要がある場合があります。

コンパイルのたびに、どちらが実行されたかが表示されます — xelatex · system または xelatex · wasm。

開発

npm install
npm run typecheck    # tsc for the server and the UI
npm run build:ui     # build the React workspace to ui/dist
npm test             # the unit suite — engine-free, no browser, seconds
npm start            # run the server on stdio (for a manual MCP client)

意図的に二段階に分けています。npm test では、コメントストア、アンカーの照合、行と列のジオメトリ、履歴リポジトリ、アセットのパス、コンパイルログの分類、プレビューサーバーのシャットダウン、MCP ワークフローの E2E をテストします。ブラウザーも TeX エンジンも不要なため、高速かつ決定的に実行できます。CI（.github/workflows/ci.yml）では、すべてのプッシュとプルリクエストに対して、Node 20 と 22 で型チェック、UI のビルド、このテストスイートを実行します。

ユニットテストでは構造上確認できないこと、つまり複数のズームレベルでのハイライトのジオメトリ、レンダリング失敗時に読者に実際に何が伝わるか、シャットダウン時にサーバーが終了し、開いているウィンドウに警告が表示されるかどうかは、scripts/smoke-*.mjs にあり、.github/workflows/smoke-macos.yml で実際のブラウザーと実際のコンパイルを使って実行します。これらはそれぞれ、ユニットテストがすべて成功していたにもかかわらず、何かが壊れた状態でリリースされたことをきっかけに追加されました。どちらのテストも成功する状態を維持し、変更に合わせてカバレッジを追加してください。

ドキュメント

• ユーザーガイド — 日常的な使い方、コメントのワークフロー、Visual モード、ファイルツリー、論文を Overleaf に移す方法、パッケージの対応状況。
• エージェントのワークフロー — トリガーとしてのコメント、/loop による自動実行、レビュアー → ゲート → 解決者のワークフロー、⚡ /ultra-agents。
• ロードマップ — 並行エージェント向けにリリース済みの機能と、真の並列マルチエージェント編集に必要なもの。
• アーキテクチャ — ヘッドレスブラウザーを使う理由、各モジュールの役割、コンパイルのフロー。

4 つすべてのドキュメントは、この README と同じ 8 言語に翻訳されています。各ページの上部には、それぞれ言語切り替えメニューがあります。

ロードマップ

複数の Claude Code セッションが、コメントやチェックポイント履歴を破損させずに、すでに同じプロジェクトで同時に作業できます（docs/ROADMAP.md を参照）。真の並列マルチエージェント編集（レビュアー／作成者／ディフェンダーがそれぞれ独自の git ブランチで作業し、変更を統合すること）が次のマイルストーンです。

このプロジェクトをスポンサーする

MagicTeX は無料のオープンソースソフトウェア（AGPL-3.0）です。論文作成の時間短縮に役立った場合は、ぜひ**このプロジェクトへのスポンサー**をご検討ください。継続的な開発の資金になります。リポジトリに ⭐ を付けていただけるだけでも助かります。

謝辞

MagicTeX は Zoe Lin が、Claude Code を使って開発・保守しています。

自分の本の仕上がりに納得せず、Knuth が自作の組版システムを作るのに 10 年を費やしたという話を教えてくれた David Turnbull に感謝します。このプロジェクトが異議を唱え続けているのは、その話です。また、texlyre-busytex のメンテナーの皆さんにも感謝します。WASM 版 TeX Live がなければ、これらすべてをローカルで実行することはできませんでした。

ライセンス

AGPL-3.0-or-later — このプロジェクトが基盤としている texlyre-busytex エンジンと同じライセンスです。THIRD_PARTY_NOTICES.md をご覧ください。