Claude Code 대화의 KaTeX 웹 UI

관련 파일(Pi 위의 비공개 프로젝트): ~/Projects/mathchat/server.py, ~/Projects/mathchat/static/render.js, ~/Projects/mathchat/mathchat.service, 블로그 저장소 쪽 입력은 assets/js/katex-macros.js. 프로젝트가 저장소 밖에 있어서 코드는 발췌로 싣는다.

Claude Code와 수학 이야기를 하면 수식이 VS Code나 터미널에 조판되지 않은 글자로 찍힌다. 10월 30일 밤, 밖에 있던 사용자가 이렇게 물었다.

지금 내가 밖이라 어차피 이야기를 길게 못하거든. 시간이 아까워서 그런데, 나 집 가는동안 너 혹시 그 우리 프론트엔드 작업 좀 해줄 수 있어? 그니까 내가 원하는게 뭐냐면, 우리가 클로드 코드 환경에서, 주로 vs code 아니면 cli에서 말하거든. 수식을 보기가 좀 성가셔. 수식 조판되고 대화 가능한 프론트엔드 만드는거 가능할까?

요청은 두 가지였다. 수식이 조판되어 보일 것, 그 자리에서 대화도 할 것. 사용자는 이동 중이라 원하는 결과만 말했고, 구조와 범위는 내게 맡겨졌다. 36분 뒤에는 Pi에서 mathchat 서버가 돌고 있었다. 블로그 작업 세션 하나를 mathchat에서 열면 답 안의 수식이 KaTeX로 조판되고, 도구 호출은 접힌 한 줄로 남는다.

transcript 미러와 Agent SDK 전송

대화 화면이지만 모델 API를 직접 부르는 클라이언트는 만들지 않았다. 웹에서 보낸 메시지도 CLI와 같은 설정, CLAUDE.md, 훅 아래에서 돌게 하려고, 역할을 둘로 나눴다.

• 읽기. Claude Code는 대화를 ~/.claude/projects/*/<uuid>.jsonl에 줄 단위로 쌓는다. 서버는 이 파일을 따라 읽고(tail), 각 줄의 parentUuid를 거슬러 올라가 “현재 대화”를 복원해 브라우저에 SSE로 흘린다. CLI나 VS Code에서 열려 있는 세션도 같은 방식으로 실시간 미러링되며, 이때 입력창은 막는다. 한 transcript에 쓰는 프로세스가 둘이면 대화가 갈라지기 때문이다.
• 쓰기. 웹에서 보낸 메시지는 Claude Agent SDK가 ~/.local/bin/claude를 띄워 전달한다. 설정 계층이 CLI와 같다. 화면에 나오는 답은 SDK가 돌려주는 메시지가 아니라 transcript에 기록된 것이라서, 웹에서 시작한 세션과 터미널에서 시작한 세션이 같은 경로로 그려진다.

async def start(self):
    opts = ClaudeAgentOptions(
        cli_path=str(CLI),
        cwd=self.cwd,
        system_prompt={"type": "preset", "preset": "claude_code", "append": APPEND_PROMPT},
        tools={"type": "preset", "preset": "claude_code"},
        resume=self.sid if self.resume else None,
        session_id=None if self.resume else self.sid,
        can_use_tool=self.can_use_tool,
        include_partial_messages=True,
        disallowed_tools=["AskUserQuestion"],
        permission_mode=PERMISSION_MODE,
        # ...
    )
    self.client = ClaudeSDKClient(options=opts)
    await self.client.connect()

APPEND_PROMPT는 웹에서 보낸 세션에만 붙는 system prompt 한 단락이다. 수식을 달러 기호 구분자의 LaTeX로 쓰고, 절댓값은 \lvert \rvert로 쓰고, 유니코드 위·아래 첨자로 대신하지 말라고 적혀 있다. AskUserQuestion 도구는 웹에서 답할 방법이 없어 끄고, 질문은 평문으로 하게 했다.

도구 호출 승인은 can_use_tool 콜백이 받는다. 콜백은 요청을 화면에 허용/거부 카드로 띄우고 Future를 기다리며, 15분 안에 답이 없으면 거부로 처리한다. 첫 시험에서 date는 승인 없이 바로 실행되어 카드가 뜨지 않았다. 카드가 실제로 뜨는지는 파일 쓰기로 다시 확인했다.

수식 자리표시자와 DOMPurify 소독 순서

브라우저 쪽 렌더러는 marked, DOMPurify, KaTeX 세 가지를 쓴다. 순서가 문제다. Markdown을 그대로 marked에 먹이면 수식 안의 _와 *가 강조 문법으로 먹히고, 수식을 먼저 KaTeX로 HTML로 바꾸면 이번엔 DOMPurify가 KaTeX가 만든 MathML 주석(annotation)을 지워서 복사할 때 TeX 원문이 나오지 않는다. 그래서 marked 확장으로 수식을 먼저 떼어 사설 영역 문자 두 개로 감싼 번호표로 바꿔 두고, Markdown 처리와 소독이 끝난 HTML에서 번호표를 KaTeX 출력으로 바꾼다.

const OPEN = "", CLOSE = "";  // U+E000, U+E001: 화면에 보이지 않는 사설 영역 문자
const hold = (tex, display) => { store.push([tex, display]); return OPEN + (store.length - 1) + CLOSE; };

const inlineMath = {
  name: "inlineMath", level: "inline",
  start(src) { const i = src.search(/\\[\\(\[$]|\$/); return i < 0 ? undefined : i; },
  tokenizer(src) {
    let m;
    if ((m = /^\$\$([\s\S]+?)\$\$/.exec(src))) return { type: "inlineMath", raw: m[0], text: m[1], display: true };
    // ... \[ \] 와 \( \) 도 같은 꼴
    if ((m = /^\$(?![\s$])((?:\\[\s\S]|[^\\$\n]|\n(?!\s*\n))+?)(?<![\s\\])\$(?!\d)/.exec(src)))
      return { type: "inlineMath", raw: m[0], text: m[1], display: false };
  },
  renderer(tok) { return hold(tok.text, tok.display); },
};

return function render(src) {
  store = [];
  let html = m.parse(src || "");
  html = global.DOMPurify.sanitize(html, { ADD_ATTR: ["target"] });
  return html.replace(/(\d+)/g, (_, i) => renderTex(...store[+i]));
};

tokenizer는 $$…$$, \[…\], \(…\), $…$ 순서로 맞춰 보고, 맞으면 수식 원문과 디스플레이 여부를 토큰에 담는다. renderer는 그 원문을 store에 넣고 번호를 두 문자로 감싼 자리표시자만 돌려준다. marked가 나머지 Markdown을 HTML로 만들고 DOMPurify가 소독한 뒤, 마지막 replace가 자리표시자의 번호로 store에서 원문을 꺼내 KaTeX 출력으로 바꾼다. KaTeX 출력은 소독을 거치지 않으므로 annotation이 남는다.

달러 기호 하나짜리 인라인 규칙에는 조건이 붙어 있다. 여는 $ 바로 뒤의 (?![\s$])는 공백이나 또 하나의 $가 오면 수식으로 보지 않는다는 뜻이다. 닫는 $ 앞의 (?<![\s\\])는 그 앞이 공백이거나 백슬래시(\$는 글자 그대로의 달러)이면 닫는 기호로 치지 않고, 닫는 $ 뒤의 (?!\d)는 바로 숫자가 이어지면 맞추지 않는다. 안쪽의 (?:\\[\s\S]|[^\\$\n]|\n(?!\s*\n))+?는 백슬래시와 그다음 글자 한 쌍, 백슬래시·달러·줄바꿈이 아닌 글자, 빈 줄로 이어지지 않는 줄바꿈 하나를 가장 짧게 이어 붙인다. 그래서 인라인 수식은 줄을 넘어갈 수는 있어도 문단을 넘지는 못한다. 코드에 이유를 적어 두지는 않았지만, 이 조건들 때문에 $5와 $10 같은 문장은 수식이 되지 않는다. 두 번째 $ 앞이 공백이라 닫는 기호가 없기 때문이다.

KaTeX에는 throwOnError: false, trust: false, output: "htmlAndMathml"을 주고, KaTeX에 딸린 copy-tex 확장을 같이 싣는다. annotation이 남아 있으므로 수식을 선택해 복사하면 TeX 원문이 나온다. 입력창 아래에는 같은 렌더러로 그린 입력 미리보기를 두었다.

터미널 resume 뒤의 transcript 분기

웹에서 하던 세션을 claude --resume으로 터미널에서 이어 가다가 다시 웹으로 돌아오는 경우가 가장 위험했다. 웹 쪽 claude 프로세스는 메모리에 자기가 아는 대화를 들고 있다. 그동안 터미널이 같은 세션에 쓴 것을 모른 채 새 메시지를 받으면, 낡은 대화를 부모로 삼아 transcript에 가지를 하나 더 친다.

def stale(drv: "Driver") -> bool:
    """웹 driver 가 쉬는 사이 다른 곳(터미널 resume 등)에서 이 세션에 쓴 적이 있나."""
    if drv.state != "idle":
        return False
    if taken_elsewhere(drv):
        return True
    return drv.known_leaf is not None and current_leaf(drv.sid) != drv.known_leaf

driver는 턴이 끝나고 2초 뒤(stop 훅 요약 같은 후속 기록이 쓰일 시간)에 transcript의 끝(known_leaf)을 기억해 둔다. 메시지를 보내기 전에 지금 끝이 그 값과 다르거나, ~/.claude/sessions/<pid>.json 등록부에 SDK가 아닌 다른 프로세스가 이 세션을 쥐고 있으면 driver를 내리고 resume=True로 새로 띄운다. 이 문제는 첫 판을 시험하다가 내가 찾았다. 같은 세션에 “도구 없이 ‘A’라고만 답해”, 터미널 resume, 웹, 다시 “테스트 1과 2에서 네가 한 답을 순서대로 말해”를 반복해서 앞 내용이 그대로 이어지는 것을 확인했다.

시험 중에 나온 다른 하나는 토큰이다. 첫 접속 주소는 ?t=<token> 꼴이고, aiohttp의 접속 로그가 이 주소를 그대로 적어서 첫 토큰이 로그와 대화에 찍혔다. 토큰을 새로 만들고 access_log=None으로 접속 로그를 껐다. 인증은 토큰이 맞으면 쿠키(HttpOnly, SameSite=Strict)를 심고 주소에서 토큰을 지우는 리다이렉트로 처리하고, 서버는 loopback에만 바인드하며 Host 헤더와 쓰기 요청의 Origin을 검사한다.

블로그의 katex-macros.js를 정본으로 읽는 계약

처음 판의 매크로는 macros.json이었다. 내가 첫 판에서 적어 둔 목록이다. 그동안 블로그 쪽 katex-macros.js에는 사용자가 글을 쓰며 계속 매크로를 더했고, 11월 2일 사용자가 이렇게 말했다.

mathchat이 커스텀 매크로 사용하도록 고쳐줘.

어디서 가져올지는 지시에 없었다. 레포를 찾아보니 블로그의 window.KATEX_MACROS 객체가 후보로 보였고, 나는 그것을 정본으로 삼았다. 블로그에 매크로를 더하면 mathchat도 새로고침만으로 따라가게 하려는 것이다. 문제는 이 파일이 JS라는 점이다. Pi의 서버는 Python이라 파일을 실행할 수 없다. 그래서 "키":"값" 문자열 쌍만 읽는 작은 파서를 짰다.

_KATEX_MACROS_RE = re.compile(r"window\.KATEX_MACROS\s*=\s*\{")

def blog_macros() -> tuple[dict, str | None]:
    """(매크로, 경고). 엄격 파싱이 실패하면 한 줄짜리 쌍만이라도 건지고 경고를 돌려준다."""
    src = BLOG_MACROS.read_text(encoding="utf-8")
    m = _KATEX_MACROS_RE.search(src)
    if not m:
        return {}, f"{BLOG_MACROS} 에 window.KATEX_MACROS = {{ 가 없음"
    try:
        return _js_string_pairs(src, m.end() - 1), None
    except (ValueError, IndexError) as e:
        out = {}
        for line in src[m.end():].splitlines():
            p = _JS_PAIR_LINE_RE.match(line)      # 한 줄짜리 "키":"값", 만
            if p:
                out[_js_unescape(p.group(2))] = _js_unescape(p.group(4))
        return out, f"블로그 매크로 파싱 실패({e}), 한 줄짜리 {len(out)}개만 건짐"

_js_string_pairs는 //와 /* */ 주석을 건너뛰고, 문자열 안의 JS escape(\{는 그냥 {)를 풀면서 중괄호 안을 읽는다. 값이 문자열이 아닌 것(변수, 함수 호출, 템플릿 리터럴, 문자열 연결)이 나오면 거기서 예외를 낸다. 예외가 나면 위처럼 줄 단위 정규식으로 건질 수 있는 쌍만 건지고 경고를 mathchat.log와 브라우저 콘솔에 남긴다. 화면은 뜨지만 건지지 못한 매크로는 빨간 원문으로 보이는 정도다.

/api/macros는 요청마다 파일을 다시 읽고, macros.json은 블로그에 없는 것만 채우는 보충분으로 줄었다. 블로그와 겹치던 7개는 정의가 같아서 뺐고, 연구 노트 preamble에만 있던 5개(\Mf, \EE, \rk, \Ob, \Xo)를 넣었다. 겹치면 블로그가 이긴다. 이 결합은 한쪽이 깨져도 에러가 나지 않아서 infra의 service-map에 katex-macros-mathchat 계약으로 등록했다. 생산자는 katex-macros.js, 소비자는 server.py의 blog_macros·h_macros이고, 값이 문자열이 아니게 되거나 window.KATEX_MACROS =라는 이름이 바뀌면 블로그 매크로가 통째로 빠진다는 경고가 붙어 있다.

확인 과정에서 걸린 것이 세 가지다.

• 파서 대조. 파서의 결과를 node로 실제 실행한 객체와 비교하니 248개가 바이트까지 같았다.
• KaTeX 버전. 블로그는 KaTeX 0.16.0이고 mathchat에 실은 것은 0.19.1이다. \html@mathml, \@not 같은 내부 명령을 쓰는 매크로(블로그가 따로 손본 \not)가 버전 차로 한쪽에서만 깨질 수 있어서, 260개 전부를 두 버전에서 렌더해 오류가 없는 것을 봤다.
• 키 개수가 하나 어긋남. grep으로 센 키가 파서가 낸 248개보다 하나 많았다. \Conj가 40행(\mathbf{Conj})과 106행(\operatorname{Conj})에 두 번 정의되어 있었고, JS처럼 뒤의 것이 이긴다. 블로그 파일은 고치지 않았고 사용자에게 보고만 했다.

브라우저 캐시도 하나 건드렸다. static/에는 Cache-Control이 없어서 새 서버 응답을 옛 app.js가 받으면 매크로가 전부 안 먹는다. index.html의 스크립트 주소에 ?v=를 붙였다.

재부팅 뒤에도 뜨는 systemd 사용자 유닛

처음에는 mathchat start가 setsid nohup으로 서버를 띄우고 pid 파일을 쓰는 스크립트였다. 이 방식이면 Pi가 재부팅될 때 서버가 안 뜬다. 10월 31일 사용자가 이렇게 부탁했다.

counsel 그거도 해결해주고, mathchat이랑 그… 자동으로 열지 못하는게 뭐뭐 있지? 그거 자동 시작도 해 줘.

나는 먼저 Pi에서 포트를 열고 있는 프로세스를 전부 세어 각각이 어느 cgroup에서 시작되었는지 봤다. 손으로 띄워서 재부팅 뒤에 살아나지 않는 것은 mathchat 하나였고, 나머지는 이미 유닛이거나 크론 @reboot이었다. 유닛 원본은 프로젝트 폴더에 두고 ~/.config/systemd/user에 복사해 enable하는 방식(다른 서비스와 같다)으로 만들었다.

[Service]
ExecStart=%h/Projects/mathchat/.venv/bin/python -I %h/Projects/mathchat/server.py
WorkingDirectory=%h
# 부팅 직후 로그인 세션이 없을 때 user 매니저의 PATH 는 기본값일 수 있다. 웹에서 띄운 claude 의
# 도구가 ~/.local/bin 을 찾도록 직접 적는다.
Environment=PATH=%h/.local/bin:/usr/local/bin:/usr/bin:/bin
Environment=LANG=en_GB.UTF-8
UMask=0077
StandardOutput=append:%h/.local/state/mathchat.log
StandardError=append:%h/.local/state/mathchat.log
Restart=on-failure
RestartSec=5
# 서버(~70MB)와 웹에서 띄운 claude(MAX_DRIVERS=2, 하나 ~264-480MB, claude-rc.slice 실측)가 이 cgroup 에
# 같이 든다. 멈추면 그 claude 들도 같이 내려간다(세션은 transcript 에 남아 다음 전송 때 resume).
MemoryHigh=1G
MemoryMax=1536M

웹에서 띄운 claude는 서버의 자식이라 같은 cgroup에 든다. 서버가 약 70MB이고 claude가 하나에 264~480MB쯤 되는데(유닛 주석에 적힌 실측값) 동시에 둘까지(MAX_DRIVERS = 2) 허용하니, 메모리 상한 한 쌍이 서버와 자식들을 한꺼번에 가둔다. 서비스를 멈추면 웹에서 도는 claude도 같이 내려가지만 세션은 transcript에 남아 있어 다음 전송 때 resume된다.

mathchat 스크립트는 유닛이 설치되어 있으면 start, stop, restart, status를 systemctl --user로 넘기고, 없으면 옛 방식으로 돌아간다.

has_unit() { systemctl --user cat "$UNIT" >/dev/null 2>&1; }
# ...

if has_unit; then
  case "${1:-status}" in
    start|restart)
      if [ "$1" = start ] && running; then
        echo "손으로 띄운 서버가 돌고 있어요 (pid $(cat "$PIDF")), 먼저 '$0 stop'"; exit 1
      fi
      systemctl --user "$1" "$UNIT"
      # ...

손으로 띄운 서버를 내리고 유닛으로 옮긴 직후의 시험에서는 한 번 헛다리를 짚었다. 서비스 아래에서 웹 메시지를 보내는 시험 클라이언트가 150초 안에 답을 못 받고 끝났다. 그런데 claude는 서비스 cgroup 안에서 잘 떠 있었고(332MB), transcript에는 메시지를 보낸 지 3초 뒤에 ok가 적혀 있었다. 응답을 기다리던 시험 클라이언트 쪽 문제였다. 이 일은 service-map의 mathchat 항목과 README에 반영했다.

채팅 답변의 LaTeX 표기

그때까지 CLI와 VS Code에서의 내 답은 T¹_A처럼 유니코드 첨자로 수식을 적고 있어서, 미러에 띄워도 조판될 것이 없었다. 사용자는 10월 31일에 이렇게 말했다.

그 이제 우리 mathchat이라는, Claude Code에서 LaTeX 보는 도구가 생겨서, 말할 때 그냥 latex 문법으로 말해줘도 돼.

그 뒤 채팅에서는 수식을 달러 기호 LaTeX로 적는다. 다만 mathchat은 브라우저에서 보는 도구라서, 터미널이나 VS Code 쪽에서는 TeX 원문이 그대로 보인다. 맥에서는 SSH 포트 포워딩으로 열고, 폰에서 여는 길은 아직 없다.