Claude Code에 기능 추가하기: 대화 사용량 표시와 위험한 명령 확인

Claude Code로 긴 작업을 하면서 대화가 얼마나 쌓였는지 항상 보고 싶을 수 있습니다. 파일을 지우는 명령이 나오면 실행 전에 지울 대상을 보여 주면 좋겠다는 생각도 듭니다. 모드(mod)는 이런 기능을 Claude Code에 덧붙이는 작은 프로그램입니다. 이 글은 대화 사용량을 날씨처럼 표시하는 예제로 모드의 동작 방식과 만드는 순서를 설명합니다.

한눈에 보기

• 모드는 Claude Code를 사용하는 동안 함께 실행되는 작은 JavaScript 또는 TypeScript 파일입니다. 상태를 확인하거나 실행 직전의 동작을 바꾸고, 내가 정한 정보를 화면에 표시할 수 있습니다.
• 말로 설명하면 Claude가 만들어 주고, 직접 짜고 싶으면 빈 폴더에서 시작합니다.
• 모드는 추가 기능을 설치하는 묶음인 플러그인 안에 들어갑니다. 특정 동작이 일어날 때 내 코드를 실행하는 훅(hook)으로 연결합니다.
• 예제는 사용량을 보여 주는 Token Weather, 위험 명령의 영향을 보여 주는 Blast Radius, 수정 내용을 되돌아보는 Replay Theater입니다.

원문 소개

Addy Osmani가 2026년 10월 1일에 쓴 튜토리얼입니다. Claude Code 2.1.287 이상이 필요합니다. API를 몰라도 말로 설명해 시작할 수 있어서 Claude Code를 자주 쓰며 도구를 내 방식에 맞추고 싶은 개발자에게 잘 맞습니다. 원문: Getting started with Claude Code mods .

모드는 어떻게 동작하나

Claude Code가 도구를 호출하거나 답변을 마치는 순간에는 이벤트가 발생합니다. 이벤트는 어떤 동작이 일어났다는 알림이고 훅은 그때 실행할 내 코드입니다. 예를 들어 파일을 고친 뒤 변경 내용을 기록하는 훅을 붙일 수 있습니다.

모드의 파일은 플러그인 폴더에 둡니다. hooks.json이 실행할 모듈, 즉 코드 파일을 가리킵니다. 파일의 register 안에서 on(이벤트, 훅) 으로 어떤 이벤트에 어떤 코드를 실행할지 연결합니다.

여러 훅은 중간 처리 단계인 미들웨어처럼 순서대로 이어집니다. 내 훅이 next(e) 를 호출하면 이벤트를 다음 단계에 넘깁니다. 끝까지 넘어가면 Claude Code가 원래 동작을 실행합니다. 이 구조에서 내 훅은 다음 일을 할 수 있습니다.

• 관찰: 원래 동작은 그대로 실행하고 결과를 기록합니다. 어떤 파일을 수정했는지 남기는 식입니다.
• 재작성: 실행 전에 이벤트 내용을 바꿔 넘깁니다. 명령을 더 안전하게 바꾸는 식입니다.
• 응답: next 를 호출하지 않고 훅이 직접 답합니다. 실행을 거절해야 한다면 도구 호출이 다음 단계로 가지 않게 할 수 있습니다.

핵심은 next를 호출하는지입니다. 호출하면 다른 훅을 거쳐 원래 동작까지 이어지고 결과를 받습니다. next를 호출하지 않고 직접 응답하면 그 동작은 내 훅에서 끝납니다.

도구 호출 외에도 프롬프트 제출, 한 차례 작업인 턴의 시작과 끝, 슬래시 명령, 화면을 그리는 ui.render가 이벤트에 포함됩니다.

모듈은 사용할 수 있는 기능을 제한한 실행 환경인 샌드박스에서 동작합니다. 웹페이지 구조를 직접 다루는 DOM이나 일반적인 서버용 JavaScript 환경인 Node는 없습니다. 대신 Claude Code가 제공하는 $ 객체로 세션과 화면에 접근합니다.

기존 설정 훅은 필요할 때 터미널에서 쓰는 셸 명령을 실행하지만 모드는 세션 내내 살아 있습니다. 그래서 앞선 상태를 기억하며 화면을 갱신하고 패널을 열 수 있습니다. 새 슬래시 명령이나 모델이 호출할 도구도 등록할 수 있습니다.

첫 모드: Token Weather

컨텍스트 창은 모델이 한 번에 참고할 수 있는 대화와 자료의 범위입니다. Token Weather는 턴이 끝날 때마다 이 범위가 얼마나 찼는지 읽고 프롬프트 위에 한 줄로 표시합니다. 토큰은 그 사용량을 세는 단위이며, 날씨 문구는 사용량에 따라 바뀌는 표시입니다.

사용 토큰, 최근 12턴의 막대 그래프, 직전 턴에서 늘어난 양도 함께 표시합니다. 현재 얼마나 찼는지와 최근 얼마나 빠르게 늘었는지를 같이 볼 수 있습니다.

원문의 실제 세션 그림은 200k 창이 18%, 67%, 81% 찼을 때를 차례로 보여 줍니다.

그림 1. 원문의 실제 한 줄 표시입니다. Clear는 맑음, Showers는 소나기, Storm은 폭풍을 뜻하며 대화가 차는 정도를 나타냅니다. 오른쪽 작은 막대는 최근 턴의 사용량 변화입니다. 출처: 원문 .

사용률이 단계 경계를 넘을 때마다 날씨 문구와 색이 바뀝니다. 18%는 Clear, 67%는 Showers, 81%는 Storm 구간입니다.

가장 간단한 시작은 claude 를 실행해 원하는 표시를 말로 설명하는 것입니다. 핫 리로드는 파일을 고치면 프로그램을 재시작하지 않고 다시 읽는 기능입니다. 이를 허용하면 모드를 만든 턴이 끝날 때 화면에 나타납니다. “Storm을 70%부터로” 같은 수정도 말로 요청할 수 있습니다.

직접 작성하는 원문 예제는 약 80줄입니다. 구현 흐름은 다음과 같습니다.

• claude --plugin-dir 로 개발 중인 플러그인을 불러옵니다. 파일을 저장할 때마다 다시 읽으므로 수정 결과를 곧바로 확인할 수 있습니다.
• 현재 사용량은 $.session.usage() 로 읽고, 이전 턴의 기록은 $.state 에 저장합니다. 일반 모듈 변수는 핫 리로드 때 초기화됩니다. $.state 는 세션 동안 유지되므로 화면을 고쳐도 사용량 기록이 남습니다.
• claude plugin validate 로 플러그인 구성을 검증하고 claude plugin test 로 동작을 테스트합니다.

파일을 저장해 모듈이 새로 로드돼도 $.state 에 쌓아 둔 기록은 그대로 남습니다.

공유와 더 큰 모드 두 개

공유하려면 GitHub 저장소에 설치할 플러그인 목록인 마켓플레이스 파일을 둡니다. 사용하는 쪽은 /plugin marketplace add 로 그 목록을 등록하고 /plugin install 로 설치한 뒤 /reload-plugins 로 다시 불러옵니다.

모드는 내 컴퓨터에서 Claude Code와 같은 권한으로 실행되는 코드입니다. 게시자가 작성한 모드가 Anthropic의 공식 코드인 것은 아닙니다. 앞서 말한 샌드박스는 모듈이 사용할 인터페이스를 제한한다는 뜻이며 설치한 코드의 모든 동작이 안전하다는 보증은 아닙니다. 원문은 일반 소프트웨어 패키지처럼 저장소를 먼저 읽고 신뢰하는 사람이 올린 것만 설치하라고 당부합니다.

• Blast Radius: 파일을 지우는 rm -rf, 저장하지 않은 변경을 버릴 수 있는 git reset --hard, 원격 변경 이력을 덮어쓸 수 있는 강제 푸시 등을 실행 전에 가로챕니다. 영향 범위를 계산하고 Proceed(진행)와 Cancel(취소)을 고르는 패널을 보여 줍니다. 원문 그림의 rm -rf build 는 지울 파일 9개(1.1 MB)를 표시합니다. 다만 명령어 문자열만 읽기 때문에 다른 명령의 실행 결과를 끼워 넣는 $(…), 명령의 별칭, rm 을 내부에서 부르는 스크립트는 놓칠 수 있습니다. 원문은 보조 안전망으로 쓰되, 실행을 확실히 막으려면 권한 규칙을 쓰라고 합니다.
• Replay Theater: 한 턴의 편집 도구 Edit와 파일 쓰기 도구 Write를 기록합니다. r 키나 /replay 로 수정 전후 차이인 diff를 한 장씩 볼 수 있습니다. 파일 변경은 그대로 진행하고 기록만 남기는 관찰형 모드입니다.

그림 2. Blast Radius가 실행 전에 버려질 파일 두 개를 보여 줍니다. Proceed는 진행, Cancel은 취소입니다. 출처: 원문 .

그림 3. Replay Theater에서 파일 수정 내용을 한 단계씩 확인합니다. Prev는 이전, Next는 다음, Close는 닫기입니다. 출처: 원문 .

위험 명령이 아니면 그냥 지나가고 위험 명령만 사람의 선택을 거칩니다.

인사이트

여기서부터는 원문이 아니라 이 블로그의 해석입니다.

1. 모드를 설계할 때는 동작을 기록할지, 실행 전에 바꿀지, 실행을 멈추고 모드가 직접 응답할지부터 정하면 이해하기 쉽습니다. 파일 수정 내역은 기록만 남기고, 위험한 명령은 실행 전에 영향을 보여 주는 식입니다. 데이터베이스 쿼리도 실행 전에 어떤 데이터를 조회하거나 바꿀지 보여 주고 승인받게 만들 때 Blast Radius의 방식을 참고할 만합니다.

2. 대화와 자료가 얼마나 쌓였는지 계속 볼 수 있으면 언제 정리할지 판단하기 쉽습니다. 현재 사용량과 최근에 늘어난 양을 함께 보면 한도에 가까워지고 있는지도 알 수 있습니다. 에이전트를 운영할 때 확인해야 할 다른 지표도 이런 방식으로 화면에 표시해 볼 만합니다.

3. 다른 사람이 만든 모드를 설치하면 그 코드가 내 컴퓨터에서 Claude Code와 같은 권한으로 실행됩니다. 외부 코드에 문제가 있으면 내 작업에도 영향을 줄 수 있다는 뜻입니다. 팀에서 모드를 공유한다면 누가 만들었고 어떤 파일이나 명령을 다루는지 설치 전에 검토하는 절차가 필요해 보입니다.

4. 글의 세 예제를 Claude Code 2.1.289에서 직접 모드로 만들어 보니 원문과 다르게 만들 수밖에 없는 부분이 있었습니다.

   • 프롬프트 위 한 줄은 한 번에 한 모드만 그릴 수 있습니다. Token Weather가 그 자리를 쓰면 Replay Theater의 r 키 버튼을 같은 자리에 둘 수 없습니다. 그래서 Replay Theater는 상태 줄에 수정 건수를 띄우고 /replay 로 열게 했습니다.
   • Blast Radius는 원문 설명처럼 명령어 문자열만 읽습니다. ~ 나 $HOME 같은 변수가 들어간 경로는 실제 경로로 풀지 못해 “not expanded"라고만 표시합니다. 강제 푸시로 덮어쓸 원격 커밋도 마지막으로 fetch한 시점을 기준으로 셉니다.
   • 한 명령에 모드의 확인 창과 Claude Code의 권한 확인이 두 번 뜰 수 있습니다. claude -p 처럼 물어볼 사람이 없는 실행에서는 위험 명령을 항상 거부합니다.

   모드를 여러 개 함께 쓰면 화면 자리를 나눠 써야 하고, 실행 전 확인은 권한 규칙과 역할이 겹칩니다. 여러 모드를 설치할 때는 각 모드가 화면 어디에 그리고 어느 단계에 끼어드는지부터 확인하는 편이 좋습니다.

바로 해볼 것

• 터미널에서 claude --version을 실행해 설치된 버전을 확인합니다. 이 글의 모드 예제를 따라 하려면 2.1.287 이상이어야 합니다.
• 화면에서 계속 보고 싶은 수치 하나를 고릅니다. 예를 들어 “현재 대화 사용률과 직전 작업에서 늘어난 양을 한 줄로 보여 줘"라고 Claude에게 요청해 모드를 만들어 봅니다. 작업을 진행하며 표시가 바뀌는지 확인합니다.
• 모드를 공유하거나 설치하기 전에 코드를 읽어봅니다. 어떤 파일을 읽거나 바꾸는지, 명령을 실행하거나 막는 부분이 있는지 확인합니다. 이해되지 않는 부분은 작성자에게 설명을 요청한 뒤 설치 여부를 정합니다.

원문: Getting started with Claude Code mods