Claude Code(이하 CC)와 긴 세션을 진행하다 보면 대화가 곁가지로 새는 경우가 많습니다. 조사하던 도중에 다른 오류를 발견하고 그 원인을 추적하는 과정에서 또 다른 설정이 신경 쓰이고, 이렇게 탈선을 거듭하다 보니 어느새 '원래 뭘 하고 있었지?' 라는 상황에 놓입니다.
이에 저는 CC의 Mod 기능을 사용하여 사이드 패널에 '현재 본론'과 '얼마나 벗어났는지(탈선 정도)'를 계속 표시하도록 만들었습니다. 게다가 세션 상태에 맞춰 움직이는 Clawd 캐릭터도 배치해 두었습니다.
이 글에서는 다음 두 가지 내용을 다룹니다.
- LLM의 요약 기능 없이 본론과 탈선을 추적하는 방법
- Clawd 캐릭터를 터미널 내에서 구동하는 방법
마지막으로, 이 글 자체를 AI 에이전트에게 전달하여 동일한 것을 만들어내도록 하는 세션 구성도 소개합니다.
session-compass라는 Mod입니다. /compass로 열리는 패널(Compass)에는 5가지 위젯을 배치했습니다.
| 위젯 | 내용 |
|---|
| Clawd | 세션 상태에 따라 그림이 바뀌는 Clawd 캐릭터 (9가지 상태) |
| ... | |
| 탈선하고 있을 때는 '본론으로 돌아가기', '하나 되돌리기' 버튼이 나타나며, 이를 누르면 되돌아가기 위한 요청문이 CC로 전송됩니다. 세션을 닫아도 본론과 탈선 내용은 비망록처럼 남아있으며, 같은 폴더에서 다음 세션을 열면 '지난 세션'으로 표시됩니다. | |
작동을 확인한 환경은 Claude Code v2.1.314, macOS, 터미널은 Ghostty입니다.
Mod는 CC 내부에서 작동하는 이벤트 핸들러(hook)를 모아 놓은 플러그인입니다. CC는 도구 호출, 프롬프트 전송, 화면 렌더링 등 이벤트가 발생할 때마다 hook을 호출하며, 이 hook은 단순히 이벤트를 관찰만 하거나, 수정하거나, 직접 처리하는 것이 가능합니다. TypeScript 파일을 그대로 읽어들이기 때문에 빌드가 필요 없습니다. v2.1.287 이상 버전에서 사용 가능합니다.
최소한의 구성은 3개의 파일입니다.
session-compass/
├── .claude-plugin/
│ └── plugin.json
...
hook은 on('이벤트명', async ($, e, next) => ...) 형태로 등록합니다. 여기서 $는 Mod에서 사용할 수 있는 API($.ui, $.store, $.clock 등), e는 이벤트의 내용물, next는 CC 본래 처리를 전달하는 함수입니다.
자세한 내용은 공식 문서의 Mods overview와 Create a mod를 참고해 주세요.
초기 버전에서는 대화 요약에 Haiku를 호출했습니다. Mod를 통해서는 $.model.complete로 모델을 호출할 수 있지만, 이는 사용자 플랜이나 API 키가 필요합니다. 그래서 레이트 제한 값이 얻어질 때(구독으로 사용할 때)만 호출하도록 조건을 걸었습니다.
그럼에도 불구하고, 패널을 표시하는 것만을 위해 토큰을 사용하는 것은 아깝다고 생각했습니다. 그래서 발상을 역전시켰습니다. CC에게 매 답변 끝에 정해진 형식의 '상황란'을 작성하게 하고, Mod는 그것을 읽기만 하도록 했습니다.
상황란 작성을 지시한 내용은 ~/.claude/rules/에 배치한 다음 규칙입니다 (일부 생략).
# 답변 끝에 붙이는 상황란
탈선이나 날짜가 바뀌면서 본론과 자신의 차례를 놓치지 않도록, 메인 대화의 답변은 매번 말미를 다음 상황란으로 마무리한다.
```text
---
- 본론: 이 세션의 주 목적
- 탈선: 현재 다루고 있는 탈선의 주제
- 현황: 어디까지 진행되었는지
- 당신의 차례: 본인이 다음에 지시/확인/판단할 것
- 다음: CC가 다음에 할 것
- 5개 항목을 이 순서대로, 1개 항목을 1줄로 작성한다. 값은 60자 이내의 한 문장으로 하며, 해당되는 것이 없는 항목은 '없음'이라고 적는다.
- 본론은 본인이 주 목적 자체를 바꿀 때만 수정한다. 탈선이나 추가 질문에서는 변경하지 않는다.
- 본론과 관련성이 낮은 질문이나 별건을 다루는 동안에는 탈선란에 그 주제를 작성한다. 같은 탈선이 이어지는 동안에는 동일한 주제를 한 글자도 바꾸지 않고 사용하며, 본론 작업으로 돌아가면 '없음'으로 한다.
...
- 본론: 로그인 화면의 유효성 검사(Validation)를 수정한다
- 탈선: CI 테스트가 실패함 > Docker 메모리 부족
...
CC에게 작성하게 하면, 사람이 읽어도 이해하기 쉽다는 장점이 있습니다. 패널을 열지 않은 상태에서도 답변 말미만 보면 본론으로 돌아갈 수 있습니다.
턴의 끝(turn.complete)에, 답변 본문(`e.answer`)
)를 읽습니다. 주의한 점은 본문의 목록 항목이 우연히 “다음:”으로 시작하는 경우입니다. 따라서 마지막 12줄 안에 3개 이상의 항목이 있고, 게다가 “현황”을 포함할 때만 상황란(状況欄)으로 처리합니다.
const ITEM = /^[\s*(?:[-・]\s)?*\s(本筋|脱線|現状|あなたの番|次)\s**\s[::]:\s*(.*)$/
export const parseStatus = (answer: string): Status | null => {
const tail = answer
...
CC는 굵은 글씨나 전각 콜론을 섞어 쓰는 경우가 있으므로, 정규 표현식(正規表現)으로 그것도 수용합니다.
탈선란의 “CI 테스트가 떨어짐 > Docker 메모리 부족”
를 “>”로 나누면, 본론에서 현재 위치한 탈선까지의 경로가 됩니다. 턴마다 이전 턴의 경로와 비교하여 트리를 업데이트합니다.
- **새로운 주제가 나왔을 때**: 탈선을 만들고 분기 직전의 분기점인 “현황”과 “다음”을 돌아갈 지점으로 보관합니다.
- **경로가 짧아졌을 때** (분기점이나 본론으로 돌아갔을 때): 그 이후의 탈선을 “수렴(収束)”으로 닫고 취소선으로 지웁니다.
- **관계없는 탈선으로 이동했을 때**: 다루던 탈선을 “미수렴” 상태로 남겨두어, 나중에 “재개” 또는 “중단”을 선택할 수 있게 합니다.
규칙에서는 “같은 주제를 한 글자도 바꾸지 않고 사용하라”고 요청하지만, CC는 공백만 달리하여 쓰는 경우가 있습니다. 따라서 주제는 공백을 제외하고 비교합니다.
“본론으로 돌아가기”를 누르면 Mod는 다음과 같은 요청문을 CC에게 보냅니다.
탈선 “CI 테스트가 떨어짐”은 여기까지 하고, 본론 “로그인 화면의 유효성 검사 수정”으로 돌아갑니다.
탈선에 들어가기 전 본론 상황: 에러 메시지 문구를 고치고 테스트를 작성 중
그때 다음에 할 예정이었던 것: 테스트를 돌려서 화면에서 확인하기
...
탈선에 들어가기 전의 상황을 첨부하는 것이 중요합니다. 대화가 압축되어 CC가 본론의 세부 사항을 잊고 있더라도, 이 문장만으로 돌아갈 수 있습니다.
보내는 것은 `$.prompt.submit`입니다. 여기에 `asUser: true`를 붙이면, Mod의 이름을 밝히는 서두 없이 이용자가 작성한 문장처럼 전송됩니다.
const send = async ($: EngineInterface, text: string) => {
if (await read($, isRunning)) {
$.ui.toast('CC가 손을 비우면 보냅니다')
...
본론, 탈선, 태스크는 턴이 끝날 때마다 `$.store`에 저장합니다. `$.store`는 같은 머신에서 모든 세션이 공유하는 키-값 저장소입니다(최대 용량은 합쳐서 4MiB).
- 동일한 세션을 재개하면, 그대로 불러옵니다.
- 같은 폴더에서 다른 세션을 열면, 직전 세션을 “지난 세션”으로 표시합니다.
- “계속할 문장을 입력란에 넣기” 버튼은 본론, 현황, 다음 예정, 미수렴 탈선, 완료되지 않은 태스크를 나열한 문장을,
`$.prompt.fill`
로 입력란에 채워줍니다. 보내기 전에 수동으로 수정할 수 있도록 `submit` 대신 `fill`을 사용합니다.
파일의 내용을 처음 덮어쓰기 직전의 내용을 보관하고, 현재 내용과 대조하여 차이점(diff)을 출력합니다. 비밀 정보가 포함될 것 같은 파일이나 큰 파일은 내용은 보관하지 않습니다. `$.store`에는 용량 제한이 있으므로, 보관하는 양은 세션별로 상한선을 두고 최근 2세션 분량만 남깁니다.
`/compass diff`를 치면, 차이점을 대화 내용에 출력합니다. 이는 `$.ui.place` (v2.1.314 이후)를 사용하여 대화의 한 줄로 그려냅니다.
| 상태 | 그림 |
|---|---|
| 답변 대기 | 말풍선에 “?”, 손을 흔들어 부름 |
| ... |
몇 가지 상태는 동시에 발생할 수 있으므로, 사람의 조작 대기를 최우선으로 하여 위 표 순서대로 선택합니다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
export const moodOf = (view: PetView): Mood => {
const { now, isRunning, signals } = view
if (signals.pending.some(tool => tool.waitsFor === 'answer')) return 'awaitingAnswer'
...
Mod가 단말기에 그림을 그리는 방법을 알아보기 위해 두 가지를 시도했습니다.
- **Raster**: 문자 격자입니다. 한 칸마다 글자/글자색/배경색을 지정합니다.
픽셀 아트입니다. PNG 또는 RGBA의 픽셀 배열을 전달하는 `Image`를 사용합니다.
처음에는 `Raster`를 사용하여 절반 높이의 블록 문자를 이용해 32×22 포인트로 그리고 있었습니다. 현재는 `Image`로 옮겨와 128×88 픽셀의 그림을 32×11 칸에 표시하고 있습니다. 한 칸을 가로 4픽셀, 세로 8픽셀로 나누기 때문에 점의 수는 16배가 되었습니다.
const { Image } = $.ui.resolve(e)
return (
<Box justifyContent="center">
...
`Image`가 그림으로 표시되는 환경은 kitty, Ghostty, 그리고 전체 화면 모드의 iTerm2 3.5 이상입니다. 그 외의 터미널에서는 `alt` 문자가 (예: '작업 중') 희미하게 나타납니다. 데스크톱 앱과 VS Code 확장에는 `Image`가 없기 때문에, `e.surface`가 `terminal`이 아닐 때는 문자만 출력합니다.
그림의 소재 파일은 사용하지 않고 전부 코드로 그리고 있습니다. 픽셀을 배치하는 `plot`, 사각형을 채우는 `paint`, 문자로 그린 형태를 색상으로 대체하는 `sprite` 세 가지가 도구입니다.
const MUG_SHAPE = [
'..wwwwww.....',
'.wccccccw....',
...
사선 위에서 내려다본 2.5차원 그림을 만들기 위해, 책상 상판은 한 줄 올라갈 때마다 2픽셀 오른쪽으로 이동시키고, 정면・위・왼쪽 면을 밝기가 다른 색으로 나누어 채색했습니다. Clawd는 머리 위를 채색하지 않고, 정면 왼쪽에 어두운 면만 추가하여 두께감을 표현했습니다.
애니메이션이 발생할 때마다 페인 전체를 다시 그리면 무거워집니다. 그래서 다음 두 가지를 조합했습니다.
- 모든 프레임을 로드될 때 단 한 번만 조립하여 RGBA base64 형태로 저장합니다.
- 150ms 간격으로 `$.ui.blit`을 사용하여 Clawd의 `Image`만 다음 프레임에 교체합니다.
`$.ui.blit`은 `key`를 지정하여 그린 `Image` 내부 내용물만 교체하는 API입니다. 페인 드로잉(`ui.render`의 hook)은 실행되지 않습니다.
const animatePet = async ($: EngineInterface) => {
petTick += 1
const mood = shownMood
...
타이머(`$.clock.every`)는 페인이 보이고 Clawd 위젯을 열고 있을 때만 작동시킵니다. 접으면 멈추고, 다음에 그릴 때 다시 시작합니다.
- **허가 대기**: `tool.check`의 hook에서 CC 판정이 '사람에게 확인(ask)'이 된 도구를 기다립니다.
- **답변 대기**: CC가 질문 도구(`AskUserQuestion`)를 호출하면 기다립니다.
다만, 사람이 허가에 응한 순간은 Mod에서는 알 수 없습니다. 따라서 허가 대기 그림은 해당 도구가 끝날 때까지 계속 표시됩니다.
대화 압축에는 `session.compact`라는 이벤트가 있습니다. 그런데 내장 가드(`cc-plugin-sec-default`)가 로드되는 환경에서는 사용자가 넣은 Mod의 `session.compact` hook이 작동하지 않습니다. 가드는 관리된 설정(managed settings)이 있는 머신이나, Team 또는 Enterprise 플랜으로 로그인한 세션에서 로드됩니다 (공식 문서). settings hook 이벤트(`classic.PreCompact` 등)도 동일하게 취급됩니다.
그래서 플러그인의 `hooks/hooks.json`에도 settings hook을 작성할 수 있다는 점을 활용했습니다. 압축 전후에 작동하는 명령어가 표시 파일을 놓거나 지우고, Mod는 2초마다 그 파일이 있는지 확인합니다.
{
"modules": ["./register.tsx"],
"hooks": {
...
식별자는 세션별로 분리한다. 파일 이름으로 사용하므로, ID에 사용할 문자만 통과시킨다
SESSION_ID="$(jq -r '.session_id // empty')"
[[ "$SESSION_ID" =~ ^[A-Za-z0-9_-]+$ ]] || { echo 'hook 입력에서 session_id를 읽을 수 없습니다' >&2; exit 1; }
...
압축이 도중에 멈추면 표시(印)가 사라지지 않고 남아 있습니다. 따라서, 붙은 지 10분이 지난 표시와 그 후에 턴이 움직인 표시는 압축 중으로 간주하지 않습니다.
작동하는 서브 에이전트의 수는 2초마다 $.agent.list로 계산합니다. 하나 이상 있다면, Clawd를 반 크기로 줄여서 점프하는 그림을 만듭니다.
Raster로 그리고 있을 때, 컨베이어 벨트 그림이 깜빡거렸습니다. 그림마다 '1초당 재작성되는 칸 수'를 측정해 보니 195칸으로 다른 그림의 두 배가 넘었습니다. 프레임 간격을 300ms로 늘리고, 벨트 이음을 멈춘 후 78칸까지 줄였습니다. 시각적인 문제도 셀 수 있는 양으로 대체하면 수정하기 쉽습니다.
CC는 페인(Pane) 속의 그림을 볼 수 없습니다. 그래서 그림이 바뀔 때마다 프레임을 문자 격자로 되돌린 미리보기로 형태를 확인하도록 했습니다. 상태 선택이나 탈선 경로는 claude plugin test에서 동작하는 테스트(87건)로 커버했으며, 일부러 구현을 망가뜨려 테스트가 실패하는 경우도 확인했습니다.
그림은 재활용하지 않고, CC의 시작 화면에 있는 Clawd를 보면서 제로베이스부터 픽셀 아트로 만들고 있습니다.
↓이거
スクリーンショット 2026-11-17 16.45.38.png
Mod는 CC에게 부탁해서 작성할 수 있습니다. CC에는 plugin-authoring이라는 내장된 스킬이 있으며, Mod의 위치나 사용 중인 버전의 이벤트 및 API를 알고 있습니다. 작성된 Mod는 세션별 폴더(~/.claude/dev-mods/<세션ID>/)에 저장되며, 턴이 끝날 때마다 다시 로드됩니다.
완성 후에는 자신의 폴더로 옮기고, 현재 디렉토리를 마켓플레이스로 등록하여 user scope로 설치했습니다.
설치 전과 수정 후에는 claude plugin validate를 사용하여 Mod가 무엇을 하는지 확인합니다. session-compass의 결과는 다음과 같았습니다 (발췌).
❯ ./register.tsx hooks: session.start, command.run{command=compass}, session.end, turn.start, turn.complete, tool.call, tool.check, ui.render{component=Placed}, ui.render{component=Pane, requestId=compass}
❯ ./register.tsx calls: $.agent.list (via refreshAgents), $.clock.after (via goBackAfterCommand, wakePetAt), $.clock.every, ..., $.ui.blit (via animatePet), ..., $.ui.toast
❯ ./register.tsx env reads: HOME
calls: 라인에 $.model.complete와 $.http.fetch가 없다는 것으로 보아, 모델도 네트워크도 사용하지 않는다는 것을 알 수 있습니다. Mod는 샌드박스 외부에서 사용자 권한으로 동작합니다. 다른 사람의 Mod를 넣을 때도 이 두 줄을 읽어보는 것이 추천됩니다.
별도로 본래 과제를 기억할 필요가 없어지고, 가볍게 탈선할 수 있게 된 것은 뇌 메모리적으로 매우 상쾌한 느낌이었고 개인적으로 만들어 보길 잘했다고 생각합니다.
그리고 Clawd는 귀여워서 작업 중에 자꾸 보게 되는데, 이 역시 여유가 된다면 여러분도 한번 만들어 보시면 마치 반려동물 같아서 점차 애착이 생길지도 모릅니다(?)
과제 위젯이 비어있었기 때문에 Mod의 결함을 의심하고 조사해 보니, CC 자체가 과제 목록을 사용하지 않고 있었다는 경우도 있었습니다. 페인(Pane)은 CC의 동작을 관찰하는 창 역할도 합니다.
- 본래 과제와 탈선 경로는 LLM에게 요약시키지 않고, CC가 답변 끝에 상황란을 작성하게 하고 Mod로만 읽게 했습니다. 토큰을 사용하지 않아 사람이 봐도 이해하기 쉽습니다.
- 탈선은
>
으로 연결된 경로처럼 쓰게 했고, 돌아갈 위치를 염두에 두고 나무 구조로 만들었습니다. 돌아가기 버튼은 돌아갈 상황을 덧붙인 요청문을 보내는 방식으로 구현했습니다. - Clawd는
Image
으로 그리고, 모든 프레임을 미리 조립한 후 $.ui.blit로 교체하고 있습니다. - Mod의 hook으로는 잡을 수 없는 이벤트는 같은 플러그인의 settings hook에 표시를 남겨 보완했습니다.
이 부분은 독자가 이 글을 AI 에이전트(Claude Code 등)에게 넘겨서 비슷한 Mod를 만들어 달라고 요청할 때 참고하는 내용입니다. 사람이 읽어도 무방합니다.
AI 에이전트에게 요청:
본 절의 내용은 사용자가 '이 기사의 Mod를 만들어 달라'와 같이 요청했을 때만 사용해 주세요. 파일을 작성하거나, Mod를 로드하거나, 규칙을 설정하는 등의 작업은 사용자로부터 확인을 받은 후에 진행해야 합니다.
-
대상: Claude Code v2.1.314에서 동작을 확인했습니다. Mods는 v2.1.287 이상 버전부터 지원됩니다.
$.ui.place
은 v2.1.314 이후부터 사용 가능합니다.
-
본문 및 탈선(Deviation) 가져오기: LLM 호출 없이 진행합니다.
~/.claude/rules/
규칙을 사용하여 답변 끝에 5가지 항목(본문, 탈선, 현황, 당신의 차례, 다음)을 작성하도록 하고, turn.complete
의 e.answer 끝에서 12줄을 읽습니다. 3개 이상의 항목이면서 '현황'을 포함할 때만 상황란으로 간주합니다.
-
탈선 계층: 탈선란은 >로 구분된 경로입니다. 새로운 주제로 탈선을 만들고 돌아갈 위치를 기록하며, 경로가 짧아지면 이전의 탈선을 닫고, 무관한 탈선으로 이동하면 미해결 상태로 남겨둡니다. 주제는 공백을 제외하고 비교합니다.
-
전송: $.prompt.submit({ text, asUser: true })
입력란에만 채우려면 $.prompt.fill을 사용합니다.
-
저장: $.store
(같은 머신 내 모든 세션에서 공유되며, 총 4MiB 용량입니다.) atom
• read
• update
(claude-code로부터 읽어와서) 표시용 상태를 가집니다.
-
이미지: Image에 { rgba, width, height }를 전달합니다. kitty, Ghostty, 전체 화면 표시 iTerm2 3.5 이상에서 표시되며, 그 외는 alt를 사용합니다. 터미널이 아닌 e.surface에서는 문자를 출력합니다.
-
애니메이션: 모든 프레임을 먼저 base64로 조합한 후, $.clock.every
로 $.ui.blit({ requestId, key, source })을 실행합니다. 페인이 보이지 않을 때는 타이머를 멈춥니다.
-
압축 중 감지: 내장된 가드인 cc-plugin-sec-default가 로드되는 환경에서는 사용자의 Mod의 session.compact
와 classic.*
의 hook은 작동하지 않습니다. 플러그인의 hooks/hooks.json에 PreCompact
• PostCompact
의 command hook을 작성하고 표시 파일을 두어 읽습니다.
-
확인: claude plugin validate <dir>
의 calls:
에 $.model.complete
• $.http.fetch
이 없는지 확인합니다. 테스트는 claude plugin test를 사용합니다.
Claude Code의 Mod를 만들어 주세요. 작업 전에, 내장된 plugin-authoring 스킬을 읽고 현재 Claude Code 버전에서 사용할 수 있는 이벤트와 API를 확인해 주세요.
만들고 싶은 것:
- /compass로 열리는 사이드 페인. 위젯은 '현재', '탈선', '작업' 세 가지로 시작합니다.
...
Clawd 캐릭터도 원한다면, 이어서 다음과 같이 요청할 수 있습니다.
Compass에 세션 상태에 따라 이미지가 변하는 캐릭터 위젯을 하나 더 추가해 주세요.
- 상태는 '답변 대기', '승인 대기', '작업 중', '대기'로 시작합니다.
- 이미지는 Image에 { rgba, width, height }를 전달합니다. 모든 프레임을 로드 시점에 조합하여, $.clock.every와 $.ui.blit으로 교체합니다.
...