TeXChronicle — 섹션 인식 LaTeX 히스토리 및 실시간 편집

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

TeXChronicle은 사람 우선(human-first)의 LaTeX 작업 공간으로, 논문을 편집·렌더링·복구할 수 있는 도구입니다. 소스 편집기, 편집 가능한 Live 문서 보기, 정확한 PDF 미리보기, 앵커 주석(anchored comments), 섹션 인식(section-aware) Git 히스토리를 하나의 브라우저 창에 결합합니다. 컴파일이 성공할 때마다 원본 소스와 그에 해당하는 정확한 PDF를 기록하며, 논문의 일반적인 Git 브랜치는 건드리지 않습니다.

단독으로도 완벽하게 동작하며, LLM은 선택 사항입니다. Claude Code, Codex 등 MCP 호환 에이전트는 유용할 때 같은 파일을 편집하거나 주석을 처리할 수 있습니다. In addition, the Windows 휴대용 빌드에는 자체 컴파일러, 브라우저 런타임, Node, Git이 포함되어 있어서, 받는 사람이 로컬에 TeX를 설치하거나 Overleaf 계정을 만들 필요가 없습니다.

작업 공간

하나의 브라우저 창(Typst의 단일 화면 편집기와 LiquidText의 앵커 주석 방식에서 영감)으로 구성됩니다:

┌──────────────────────────────────────────────────────────────┐
│  ✓ 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 닫(GPX). It's the *은 semantic. Reviewer가 인한 내용을 체크하ロ지, 문서에서 텍스트를 선택하고 선택 ("이 부분 줄이세요") — 그다음 Claude에게 "내 주석 처리해줘"라고 요청하면, check_comments으로위치화된 작업 항목**을 가져감합니다. (page + 해구 부분 / 원본 file:line 앵커 + 요xv). Ru, Claude이 원본을 편집하고 후 각 카트를 해결 Δ?:

  • GPXn

  • text before; skip as closest.

• 편집 가능한 소스 패널. CodeMirror LaTeX 편집기로 project files list; save(Ctrl+S)하면 Typst처럼 PDF를 recompile/refresh. 아니면 기존의 own 편집기 그대로 사용: 저장하면 동일한 live loop가 실행. Code, Live, PDF는 전체화면 선택 가능한 작업 공간입니다. Live 일반적인 학술 LaTeX을 즉시 편집 가능한 문서로 바꿉니다 (제목, 본문, 인용, 주석, 목록, 수식, 그림, 표). 단어를 편집하면 정확히 그 소스 구간만 바뀝니다; 수식, 인용, 참조, 명령, 주석, 그대로인 형식은 ㅁ으로 유지됩니다. 보호되는 구조는 Code에서 계속 보이고 편집 가능합니다. PDF는 항상 정확합니다. Split은 비교가 필요할 때 소스 또는 Live를 PDF 옆에 놓습니다.

• PDF → 정확한 소스. 로컬 TeX backend가 만든 PDF에서 아무 곳이나 클릭하면 SyncTeX를 통해 해당 source file과 line을 엽니다. Visible-text refinement는 매크로로 확장된 title/author 블록을 처리해주고, 번들된 WASM 백엔드에 SyncTeX 맵이 없을 때는 최선을 다하는 fallback으로도 동작합니다.

• Live reload. 파일 감시자가 저장할 때마다 자동으로 다시 컴파일합니다 — Claude의 편집, 내장 편집기의 저장, 또는 외부 편집기의 저장까지모두 포함.

• 섹션 인식 변경 기록(section-aware change history). 성공한 컴파일은 자동으로 hidden git ref(refs/latex-preview/checkpoints)에 스냅샷됩니다 — 당신의 브랜치, git log, working tree는 절대 건드리지 않습니다. 복원은 먼저 나중에 되돌릴 수 있는 안전 스냅샷을 만들어 두고, 별도 마크를 통해 렌더된 적 없는복원 상태가 성공한 PDF와 잘못 혼동되지 않도록 막습니다. 히스토리는 라벨+퍼지 매칭으로 모든 살make/세요일이 절도, 임의된 로도/옮기기いて 변경 상황을 추적합니다. 전용 타임라인, 텍스트/서브트리 비교, 해당 부분만 복원, 그 체크포인트에서 생성된 정확한 PDF를 다시 열기 등이 가능합니다. 프로젝트 전체 타임라인도 제공됩니다.

• Overleaf로 이동. Download PDF, Export .zip (컴파일 입력 번들), 공개 GitHub 리포지토리용 원클릭 Open in Overleaf 링크를 제공합니다; Premium Git-bridge 동기화는 문서화되어 있는 git push로 합니다. docs/USER-GUIDE.md 참조.

• 리뷰 워크플로 (reviewer → gate → resolver). 리뷰어/방어자가 add_comment를 통해 주석을 등록하면, 당신이 Accept/Reject를 선택하거나 (자체 모드에서는 Auto-accept) 사용자가 허용한 것만 해결. 주석에는 role 과 reply thread가 포함됩니다. docs/AGENT-LOOP.md 참조.

• 저장 vs 재컴파일: 당신이 결정합니다. 내장 편집기는 30초마다 자동 저장하지만 재컴파일하지 않습니다. Ctrl+S / Save / Recompile을 하면 그 PDF가 그때 생성됩니다. (즉시 컴파일하려면 ⚡ Live 사용). 외부 편집기나 Claude의 편집은 watcher를 통해 자동 재컴파일됩니다.

• 실제 프로젝트. 자동으로 main 파일을 찾고, 여러 파일의 \input/\include 콜 등 여러 파일 참조를 통합합니다. .bib, 리포지토리 내의 .cls/.sty/.bst, figure 파일까지 수집하고, 필요하면 BibTeX 실행과 재실행을 자동으로 합니다. 누락된 패키지는 때에 따라 자동 삽입됩니다.

• 컴파일 백엔드. 로컬 latexmk가 있으면 그것을 사용하고 — 전체 패키지 충실도를 제공하고, Overleaf와 동일한 결과물을 생성 — 없으면 패키지가 포함된 설치 없는 WASM TeX Live를 사용합니다. 어느 쪽을 순 수 있는 디버깅 실행 표시? "backend": "system" 또는 "backend" : "wasm"로 강제 선택 가능하며, 컴파일 로그는 어느 것을 사용했는지 보고합니다.

• 문서 클래스. IEEEtran이 함께 제공됩니다. WASM TeX Live에는 venue 클래스가 없고, 클래스 누락은 클래스와 함께 패키지를 우회할 수 없기 때문입니다. 컨퍼런스 클래스(NeurIPS, ICML, CVPR, ACL, AAAI…)는 재배포 불가한 라이선스가 있으므로, 생략합니다. 작성자 키트의 .cls를 소스와 같은 폴더에 놓으면 자동으로 검색됩니다.

• MCP 도구: render_preview (컴파일 + 작업 공간 열기), check_comments / resolve_comment / add_comment / reply_to_comment (리뷰 루프), show_diff (이미지로 나란히 diff — 이미지 지원 클라이언트에 유용).

• 실행 가능한 오류 정보. 컴파일이 실패하면 {file, line, message} 형태로 파싱된 에러를 반환하여 Claude가 스스로 수정할 수 있고, 작업 공간에도 표시됩니다.

Related MCP server: Unofficial Overleaf MCP Server

LLM 없이 에디터 실행

휴대용 Windows 버전 (설치 불필요)

릴리스에서 TeXChronicle-<version>-Portable-Windows-x64.zip을 다운로드한 뒤, 폴더 전체를 추출하고 **TeXChronicle.exe**를 더블 클릭하십시오. 이 안에는 자체 Node 런타임, Git, 헤드리스 Chromium, 그리고 완전한 BusyTeX 에셋 번들이 포함되어 있어서, 받는 쪽에서 npm, Node, Git, Perl, TeX을 설치할 필요가 없고 첫 컴파일도 다운로드를 요구하지 않습니다. 최근 논문에서 main .tex 파일을 찾거나 그 파일을 TeXChronicle.exe에 끌어다 놓으십시오.

이 디렉터리는 설치 파일이 아니라 휴대용 폴더입니다: 하위 폴더는 EXE와 같은 위치에 두어야 합니다. 논문의 checkpoints, 주석, 저장된 render PDF는 논문의 .latex-preview 디렉터리에 유지되므로 Dropbox나 다른 폴더 동기화 유틸리티가 다른 기기로 전달합니다. 한 번에 한 대의 기계만: 같은 논문을 다른 기기에서 열기 전에 동기화를 마쳐야 하며, 두 기기에서 하나의 논문을 오프라인으로 편집하면 checkpoint 기록이 분기될 수 있습니다. 공유, 체크섬, 업데이트, 제한, 반복 빌드 명령은 휴대용 Windows 안내에서 확인하세요.

원클릭 런처 (Windows)

TeXChronicle을 설치/연동한 후 데스크톱 및 시작 메뉴 바로가기를 한 번 등록합니다:

texchronicle install-launcher

이제 외울 명령은 없습니다: TeXChronicle를 클릭하면 Recent projects 창이 이전에 열었던 논문 리스트를 보여주고, **Browse…**로 새로운 main .tex 파일을 선택할 수 있습니다. 논문을 더블클릭하면 브라우저 작업 공간이 열립니다. .tex 파일을 데스크톱 바로가기로 드래그할 수도 있습니다. 이미 실행 중인 논문을 열면 새 컴파일러를 생성하는 대신 기존 작업 공간을 재사용합니다. 작은 상태 창이 로컬 작업 공간을 살려 두며, 끝나면 닫으면 됩니다. texchronicle open으로도 같은 최근 프로젝트 선택기를 사용할 수 있습니다.

터미널 실행

npm 출시 전까지는 GitHub에서 바로 설치하면 됩니다 — clone이나 build step 없이:

cd /path/to/paper
npx -y github:Aliutin/TeXChronicle preview main.tex

npm이 저장소를 클론하고 설치한 뒤(UI 빌드 포함 — 정확히 어떤 일이 일어나고 비용이 얼마인지는 LLM/MCP 클라이언트와 설치 참조), 작업 공간을 실행합니다. npm 출시 이후에는 같은 명령이 npx -y texchronicle preview main.tex입니다.

대신 소스 체크아웃(개발자 경로)을 사용하는 경우, TeXChronicle을 한 번 설치하고 연결하세요:

npm install
npm run build:ui
npm link

npm run build:ui가 브라우저 작업 공간을 만듭니다. 이 세션이 없으면 새 클론은 기본 뷰어 — 편집기, History, 주석이 없는 PDF 패널만 — 로 동작합니다.

그런 다음 어떤 LaTeX 프로젝트 디렉토리에서든 실행:

cd /path/to/paper
texchronicle preview main.tex

그 터미널이 동작하는 동안 브라우저 작업 공간이 열리고 유지됩니다. ⚡ Live로 타이핑 즉시 재컴파일을 하거나, Ctrl+S로 저장하고 컴파일하세요. 모든 정상 렌더터가 History에 기록됩니다. 종료하려면 Ctrl+C를 누릅니다. 다른 프로젝트라면 texchronicle preview --project /path/to/paper main.tex 처럼 사용합니다. Claude Code, Codex, 그 외 MCP 클라이언트는 선택 사항입니다 — 이 독립 작업 공간이 실행되는 동안 같은 파일을 수정할 수 있지만, 이 공간을 열거나 사용하는 데 필요하지는 않습니다.

LLM/MCP 클라이언트로 설정

패키지와 MCP 메타데이터는 texchronicle 및 io.github.Aliutin/texchronicle을 사용합니다. npm 패키지는 아직 출판되지 않았으므로 — npm view texchronicle는 여전히 404 — GitHead에서 설치합니다. npm이 직접 clone 하므로 나만의 clone/build 단계가 없습니다:

1. 논문 프로젝트의 .mcp.json에 편집을 추가하세요 (.mcp.json.example 참조):

   {
     "mcpServers": {
       "texchronicle": {
         "command": "npx",
         "args": ["-y", "github:Aliutin/TeXChronicle"]
       }
     }
   }

   npm이 저장소를 클론하고 설치합니다. 이 패키지는 prepare 스크립트가 있으므로 npm이 devDependencies까지 설치하고 pack 전에 prepare를 실행합니다. 이 prepare는 다시 npm run build:ui이므로, 브라우저 작업 공간(ui/dist)은 기억해야 할 것이 아니라 설치의 일부로 자동 빌드됩니다. 그런 다음 postinstall 프로세스가 Playwright가 제공하는 헤드트리스 Chromium를 나머지 있습니다. 이 과정을 원하지 않거나 이미 있는 브라우저를 사용하려면 Requirements를 챙기십시오.

   GitHub 방식에서 알만한 세 가지가 있는데, 모두 문제가 되지는 않습니다: 실행 머신에는 **git 및 PATH**가 필요합니다; 설치 시 devDependencies(React, Vite, TypeScript)까지 받으면서 UI를 빌드하므로 일반 레지스트리 설치보다 눈에 띄게 느립니다; 그리고 이후의 npx는 항상 네트워크에서 git ref를 새로 해석하기 때문에 — 이전 실행이 얼마나 재사용되는지는 npm 버전에 따라 다릅니다.

   다른 두 가지 형식:

   • 소스 체크아웃 — 개발자 경로이자, 서버를 자체 사용하겠다면 선택하는 방법입니다. TeXChronicle 폴더에서 npm install(실행하면 prepare → npm run build:ui까지 실행)을 수행한 뒤 클라이언트가 엔트리 스크립트를 가리키게 합니다: "command": "node", "args": ["/absolute/path/to/TeXChronicle/bin/cli.mjs"]. npx tsx src/server.ts보다 bin/cli.mjs를 통하는 것이 좋습니다 — 엔트리 스크립트가 Node 버전을 검사하고, 너무 오래된 Node가 잘 알 수 없는 설명을 출력하며, 일부 Windows 계정이 필요한 os.userInfo fallback을 미리 로드하기 때문입니다. 직접 src/server.ts를 호출하면 이 두 가지를 생략하고, MCP 클라이언트가 -32000 코드로만 보고하는 방식으로 실패합니다. ui/ 아래 항목을 편집한 뒤 손으로 npm run build:ui를 다시 실행하고 — 주의: 스크립트를 생략한 클론(npm install --ignore-scripts)은 workspace 대신 basic viewer를 열 수 있고, 화면에는 이유가 설명되지 않습니다.

   • npm 출시 이후에는짧은 형태: "command": "npx", "args": ["-y", "texchronicle"].

2. Claude Code를 재시작(또는 /mcp 재연결)해야 서버를 인식합니다.

3. Claude를 렌더링하도록 하세요. 예: "이 학술 논문의 preview를 렌더링해 줘" &rarrr; 첫 번째 호출은 WASM TeX Live asset 형식 (~650 MB, 최초 한 번)을 다운로드하고, 컴파일을 수행하고, live preview 탭을 엽니다. 이후 편집하면 파일이 자동으로 다시 렌더링됩니다.

어떤 폴더가 사용되나요?

서버가 시작된 폴더입니다. Claude Code와 Codex는 프로젝트 디렉토리에서 MCP 서버를 시작하므로, 논문 옆에 있는 .mcp.json은 추가로 필요 없습니다. 일부 클라이언트 — 특히 Claude Desktop — 프로젝트 디렉토리가 아닌 홈 디렉토리에서 프로젝트 서버를 시작하므로, 그 경우 서버가 컴파일할 논문이 없습니다. 이 경우 서버의 환경설 value? For GUI: 해당 설정에서 실행 --project /path/to/paper` 등으로 폴더를 명시하세요:

{
  "mcpServers": {
    "texchronicle": {
      "command": "npx",
      "args": ["-y", "github:Aliutin/TeXChronicle"],
      "env": { "TEXCHRONICLE_PROJECT": "/absolute/path/to/paper" }
    }
  }
}

시작할 폴더를 지정하는 .mcp.json 설정 블록은 meta settings JSON column.?? Let's finalize.

또는 서버 인자로, 패키지 이름 뒤에 붙여서 지정할 수 있습니다: "args": ["-y", "github:Aliutin/TeXChronicle", "--project", "/abs/path/to/paper"] — 그리고 소스 체크아웃의 경우에는 "args": ["/abs/path/to/TeXChronicle/bin/cli.mjs", "--project", "/abs/path/to/paper"]처럼 지정합니다.

세 번째 방법은 설정 변경이 전혀 필요 없습니다. **projectRoot**를 render_preview에 넘기면 됩니다. — *"render a preview of /Users/me/papers/thesis"*라고만 해도 Claude가 알아서 채워 넣습니다. 이 인자는 세션 전체를 다시 지정하므로, 이후의 모든 도구 호출 (댓글, 기록, diff)도 그 폴더를 사용합니다. 그리고 세 가지 중 유일하게 에이전트가 대화 중간에 스스로 적용할 수 있는 방법이며, 여러분이 설정 파일을 편집하고 클라이언트를 재시작할 필요가 없습니다.

.tex 파일이 없는 곳에서 시작된 서버는 그 폴더를 감시하거나 거기에 기록 저장소를 만들지 않고, 그 사실을 알리고 종료합니다. 그리고 이 거부 메시지는 위의 세 가지 방법을 모두 안내합니다.

WASM 자산은 이 저장소에는 없습니다. 이들은 첫 실행 시 사용자별 캐시로 가져옵니다 — macOS는 ~/Library/Caches/texchronicle, Linux는 $XDG_CACHE_HOME/texchronicle, Windows는 %LOCALAPPDATA%\texchronicle — 따라서 TeXChronicle을 업그레이드해도 이들을 다시 다운로드하지 않습니다. 그리고 체크아웃, 전역 설치, npx 실행은 한 부씩 공유합니다. TEXCHRONICLE_ASSETS_DIR을 설정하면 다른 위치에 둘 수 있습니다. 미리 가져오려면: npx texlyre-busytex download-assets <that directory>.

Claude Code 플러그인으로 설치(슬래시 명령)

선택적인 Claude Code 플러그인은 MCP 서버와 그리고 슬래시 명령을 함께 제공합니다:

/plugin marketplace add Aliutin/TeXChronicle
/plugin install texchronicle

npm 릴리즈 전까지 플러그인에 번들된 서버 항목은 위와 동일한 GitHub 형식 (npx -y github:Aliutin/TeXChronicle)이므로, 같은 주의사항이 적용됩니다: PATH에 git이 있어야 하고, 첫 번째 시작은 그냥 압축을 푸는 것이 아니라 설치와 빌드를 수행합니다. 패키지가 npm에 올라가면 npx -y texchronicle로 바뀝니다.

그런 다음 논문 프로젝트에서 일반적인 흐름에는 워크플로 명령을 사용합니다:

• /texchronicle — 작업 공간(라이브 미리보기)을 컴파일하고 엽니다.

• /ai-review [skill] — 논문을 스킬로 검토하고(기본값: academic-paper-revision; 다른 스킬 이름도 전달 가능) 여러분이 수락/거절할 수 있도록 댓글을 답니다. 없는 스킬은 설치 힌트와 함께 안내됩니다.

• /address-comments — 수락한 댓글을 처리합니다(이 명령어를 /loop 60s /address-comments로 반복할 수 있습니다).

• ⚡ /ultra-agents [skill] [depth] — 완전 자동화: 검토, 자동 수락, 수정을 depth 라운드까지(기본 2회) 반복하고, 해당 라운드에서 새로운 내용이 없다면 즉시 조기에 종료합니다. 라운드마다 개별 승인은 없습니다. — 이것이 의도이자 위험입니다. depth > 5일 때는 시작 전에 확인을 요청합니다. 종료 시 요약을 제공합니다(무엇이 제기되었고, 무엇이 바뀌었고, 어떤 체크포인트를 봐야 하는지). 각 라운드는 여전히 일반적이고 되돌릴 수 있는 체크포인트입니다. 자세한 내용은 docs/AGENT-LOOP.md를 참조하세요.

하나의 도구마다 하나의 명령

모든 MCP 도구에는 동일한 이름의 슬래시 명령이 있으므로, 도구 이름을 입력하는 것만으로도 각 단계를 실행할 수 있습니다. 쉽게 가르칠 수 있는 규칙: 도구가 X이면 /X를 입력합니다.

이런 것을 반드시 입력해야 하는 것은 아닙니다. 그냥 일반 문장으로도 됩니다 ("render preview", "address my comments"). 명령은 빠르고 가르치기 쉬운 단축 표현입니다.

슬래시 명령은 플러그인과 함께 제공됩니다. 이들은 commands/ 디렉터리의 파일로, 플러그인만 설치합니다. 서버 자체는 프롬프트를 등록하지 않으므로, .mcp.json 구성으로는 아래 표의 도구는 제공하지만 / 단축 명령은 없습니다. 그 대신 일반 문장으로 사용하게 됩니다("render preview", "address my comments"). 실제로 명령도 어차피 그런 문장으로 확장되는 것뿐입니다.

도구

MCP를 사용하는 모든 클라이언트에 노출되는 MCP 표면입니다. (Claude Code에서는 그냥 일반 문장으로 요청하거나 위 슬래시 명령을 사용해도 됩니다. 어디까지나 아래이 밑에 있는 도구입니다.)

핵심 워크플로는 바로 이 위에 세워진 것이지, 그 목록 안에 있는 것이 아닙니다. /texchronicle, /ai-review, /add-address-comments와 ⚡ /ultra-agents는 위 도구들을 오케스트레이션하는 Claude Code 플러그인 명령입니다 — /ultra-agents는 여러분이 허용한 횟수만큼 검토 → 자동 수락 → 수정을 반복하며, 이 때문에 add_comment에 accepted 플래그가 있습니다. 이들은 MCP 표면이 아니므로 다른 MCP 클라이언트에게는 위의 일곱 도구만 보입니다. 플러그인 섹션과 docs/AGENT-LOOP.md를 참고하세요.

터미널에서 직접 보기

이것은 실물도구 출해입니다. 샘플 논문에 대한 실제 실행에서 그대로 담아온 것이지 모의 생성이 아닙니다. 브라우저 작업 공간(위 스크린샷)이 같은 상태를 라이브로 보여주는 동안 Claude Code에서 실제로 보게 될 내용입니다.

다음을 입력합니다:

/texchronicle

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

두 개의 입구 — 작업 공간에서는 사용자, 7개의 MCP 도구를 통해서는 에이전트 — 같은 코디네이터, 코멘트 저장소, git 히스토리에서 만난다. 사용자는 렌더링된 문서를 대상으로 동작하고(코멘트 앵커 지정), Claude는 소스를 대상으로 동작한다(check_comments로 코멘트를 읽고, 편집하며, resolve_comment로 해결). 이 공유 기반이 코멘트 루프, 리뷰 워크플로우, 추적 가능한 히스토리를 가능하게 한다.

요구 사항

아래 요구 사항은 npm/소스 설치에 적용된다. Windows 포터블 릴리스는 이러한 런타임을 자체 내장하며, 64비트 Windows 10 이상과 작업 공간 창용 일반 웹 브라우저만 필요하다. 아래에서 언급하는 TEXCHRONICLE_* 변수는 사용자 가이드에 함께 정리되어 있다.

• Node 20.19+ — chokidar와 playwright가 실제로 요구하는 하한이며, 서버가 시작 시 확인하고 그렇게 알려준다.

• Playwright의 헤드리스 Chromium(약 150–300 MB), 자동으로 내려받음: postinstall 단계가 설치 시 다운로드하고, 브라우저를 처음 필요로 할 때 그게 없으면 그때 다운로드를 다시 시도한다. 이를 바꾸는 방법:

  • TEXCHRONICLE_SKIP_BROWSER_DOWNLOAD=1(또는 Playwright 자체의 PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1)로 다운로드를 건너뛴다 — 제한된 데이터 요금제 연결, CI, 또는 오프라인에서 빌드한 이미지에서 유용하다.

  • Playwright Chromium이 없으면 TeXChronicle은 이미 설치된 Chrome 또는 Edge로 대체하고, 그렇게 될 때 알려준다.

  • TEXCHRONICLE_BROWSER는 위의 모든 것보다 우선해 하나를 명시적으로 선택한다: chrome, msedge, chromium, 또는 실행 파일의 전체 경로.

  문제 해결: 자동 다운로드가 건너뛰어졌거나 실패했고 Chrome/Edge도 발견되지 않는 경우, TeXChronicle 폴더에서 npx --no-install playwright install chromium --only-shell을 실행하면 해결된다.

• 약 650 MB 디스크, 일회성 WASM TeX Live 자산 — 전부 첫 실행 때 받으며, 세 패키지 세트(기본 87 MB, 권장 190 MB, 확장 324 MB, 그리고 31 MB 엔진)로 나뉜다. 일반 논문은 기본 세트만 로드한다. 나머지 두 개는 필요해질 때까지 디스크에 존재한다. 설치마다가 아니라 사용자마다 캐시되므로 TeXChronicle을 업그레이드해도 다시 내려받지 않는다. 위치는 TEXCHRONICLE_ASSETS_DIR로 변경할 수 있다.

• 논문 폴더 안의 디스크: 모든 성공한 렌더의 PDF를 .latex-preview/renders/<checkpoint>.pdf에 보관하여 히스토리의 PDF 보기가 이전 버전의 정확한 출력을 보여줄 수 있게 한다. 최신 50개를 유지하고 그보다 오래된 것은 삭제한다 — TEXCHRONICLE_KEEP_RENDERS를 다른 숫자로 바꾸거나, 0으로 하면 모두 보존한다. 현재 화면에 표시 중인 렌더는 오래되어도 삭제되지 않는다.

• 로컬 TeX 설치는 선택 사항이다. 언제 필요한지 아래를 참고한다.

로컬 TeX 배포판이 필요한가요?

아니 — 번들 WASM 엔진은 아무것도 설치하지 않아도 컴파일되므로, 이게 곧 핵심이다. 하지만 TeX Live의 일부만 포함하므로 없는 것도 있다: svg, 대부분의 학술대회 문서 클래스, 여러 흔하지 않은 패키지가 그렇다. 어떤 것이 없으면 잘못된 PDF를 조용히 넘겨주는 대신 알려준다.

Overleaf와 정확히 일치하는 출력이 필요할 때 배포판을 설치한다. TeXChronicle은 그걸 자동으로 인식하며 설정이 필요 없다:

latexmk는 단독으로 설치되지 않는다 — 위 배포판에 함께 들어 있는 드라이버 스크립트다. Windows에서 TeXChronicle은 기본 사용자별/시스템 MiKTeX 및 Strawberry Perl 위치를 직접 발견하므로, PATH가 오래되었거나 완전하지 않아도 번들 컴파일러를 강제하지 않는다. 그 외 OS에서는 which latexmk가 아니라 **latexmk -version**으로 확인하라: 파일이 있다고 실행할 수 있다는 뜻은 아니다. macOS에서는 확실한 터미널 대신 eval "$(/usr/libexec/path_helper)"를 먼저 실행해야 할 수 있다.

알아두면 좋은 Windows 관련 사항 두 가지, 둘 다 알아서 처리된다:

• MiKTeX의 "설치 전에 물어보기" — 새 MiKTeX Console을 설치했을 때 남아 있는 설정이다. 그 물어보기는 GUI 대화창이고, TeXChronicle은 엔진을 숨긴 채 실행하며 답해 줄 사람이 없으므로 컴파일이 그냥 멈춘다. TeXChronicle은 이 설정을 감지해 설치 프로그램을 끈 상태로 실행하고, 문서가 이 컴퓨터에 없는 패키지를 요구하면 그렇게 말해 주고 해결책을 안내해 준다(mpm --install=<pkg>, 또는 MiKTeX Console → Settings → "Always install missing packages").

• 두 개의 perl. Git Bash나 MSYS2를 사용하는 경우, POSIX 에뮬레이션 perl이 PATH에 있어서 MiKTeX의 latexkm를 실행할 수 없다. TeXChronicle이 이를 감지하여 PATH의 것보다 실제 Strawberry Perl 설치를 우선하므로 로컬 백엔드가 아무것도 조정하지 않고도 동작한다.

모든 컴파일은 어떤 것이 돌았는지 알려준다 — 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)는 모든 push와 pull request에 대해 Node 20과 22에서 타입 체크 + UI 빌드 + 그 테스트 묶음을 실행한다.

단위 테스트가 구조적으로 볼 수 없는 부분들 — 여러 줌 레벨의 하이라이트 위치, 실패한 렌더가 독자에게 실제로 무엇을 알려주는지, 종료 시 서버를 닫고 열린 창에 경고하는지 — 이브는 scripts/smoke-*.mjs에 있고, .github/workflows/smoke-macos.yml에서 실제 браузер와 실제 컴파일을 상대로 실행된다. 각각의 존재 이유는 유닛 테스트 세트가 모두 통과했는데도 깨진 채 출시된 것이 있었기 때문이다. 양쪽 다 green을 유지하고, 변경과 함께 커버리지를 추가해 주세요.

문서

• 사용자 가이드 — 일상 사용법, 코멘트 루프, Live 편집, 파일 트리, 논문을 Overleaf에 가져가기, 패키지 모지 여부.

• 에이전트 루프 — 코멘트를 트리거로 사용하는 법, /loop로 무인 실행하는 법, 리뷰어 → 게이트 → 해결사 과정, 그리고 ⚡ /ultra-agents.

• 로드맵 — 동시 멀티 에이전트를 위해 이미 있는 것과, 진짜 병렬 멀티에이전트 편집에 아직 필요한 것.

• 아키텍처 — 왜 헤드리스 브라우저인지, 각 모듈의 역할, 컴파일 흐름.

네 문서 모두 이 README와 같은 8개 언어로 번역되어 있고, 각 페이지는 상단에 자체 언어 전환기를 제공한다.

로드맵

여러 Claude Code 세션이 이미 같은 프로젝트를 코멘트나 체크포인트의 히스토리를 깨뜨리지 않고 동시에 작업할 수 있다(docs/ROADMAP.md)

• 진짜 병렬 다중 에이전트 편집(리뷰어/저자/수호자가 각자 git 브랜치에서 작업한 뒤 함께 병합하는)이 다음 마일스톤이다.

감사의 글

TeXChronicle은 Zoe Lin과 기여자들의 MagicTeX МСП 포크로 시작했으며, 이후 인간 중심의 편집과 섹션 단위 히스토리를 중심으로 설계를 크게 바꾸었다. 출처에 대해서는 NOTICE.md를 참조한다.

또한 texlyre-busytex 유지보수자에게도 감사하며, 이 프로젝트의 WASM TeX Live 엔진이 번들 컴파일러를 구동한다.

라이선스

AGPL-3.0-or-later — 기반인 texlyre-busytex 엔진과 같은 라이선스. NOTICE.md 및 THIRD_PARTY_NOTICES.md를 참조한다.