클로드 코드 Mods 설치와 안전 점검, 되는 것과 안 되는 것

클로드 코드 Mods 설치 전에 알아야 할 것을 한 번에 정리합니다. Mod로 할 수 있는 일과 못 하는 일, 사용 한도 미터 Mod를 직접 만드는 순서, 남이 만든 Mod를 깔기 전에 claude plugin validate로 점검하는 법, 마켓플레이스에서 설치하고 끄는 법까지 31단계로 따라 할 수 있습니다.

Mods는 터미널판 Claude Code 2.1.287 이상, 데스크톱 앱(Code 탭) 2.1.286 이상에서 기본으로 켜져 있습니다. 아직 초기 기능이라 버전이 올라가면 이름이나 동작이 바뀔 수 있습니다.

클로드 코드 Mod란 무엇인가

Mod는 클로드 코드 안에서 도는 내 코드입니다. 클로드 코드가 무언가를 하려는 순간, 예를 들어 도구를 쓰기 직전이나 화면의 한 부분을 그리기 직전에 내 함수를 한 번 불러 줍니다. 그 함수는 지켜보기만 할 수도 있고, 내용을 바꾸거나 아예 대신 처리할 수도 있습니다.

비슷한 기능과는 이렇게 다릅니다.

• 스킬은 클로드가 읽는 설명서입니다.
• MCP는 클로드에게 외부 도구를 붙여 주는 통로입니다.
• 설정 훅(settings hook)은 정해진 순간에 셸 스크립트를 돌리는 설정입니다.
• 화면에 직접 패널이나 띠를 그릴 수 있는 것은 Mod뿐입니다.

파일은 세 개면 됩니다. 이름표 역할을 하는 .claude-plugin/plugin.json, 코드 파일 위치를 알려 주는 hooks/hooks.json, 실제 코드인 hooks/register.js입니다. 공식 문서의 첫 예제는 도구를 쓸 때마다 숫자를 세어 스피너 옆에 보여 주는 Mod인데, 코드가 20줄 남짓입니다.

클로드 코드 Mods로 되는 것 세 가지

화면에 그리기

입력창 바로 위에 한 줄짜리 띠를 띄울 수 있고, 옆에 패널을 열 수 있습니다. 패널 안에는 탭을 여러 개 두고 입력란과 선택 상자도 넣을 수 있습니다. 마우스를 올리면 테두리 색이 바뀌거나 숨은 줄이 나타나는 호버도 됩니다(터미널과 데스크톱 앱 기준).

스피너 문구, 도구 실행 줄, 클로드가 질문할 때 띄우는 창처럼 클로드 코드가 원래 그리는 부분도 바꿀 수 있습니다. 공식 문서의 그릴 수 있는 자리(render site) 표에는 모두 13군데가 올라 있습니다. 대화 속 글을 마우스로 드래그해 고르면 그 글을 Mod에서 읽을 수도 있어서, 고른 문장을 핀보드 패널에 메모로 붙이는 식의 Mod도 만들 수 있습니다.

끼어들기

클로드가 도구를 쓰기 직전에 Mod가 먼저 봅니다. 그래서 위험한 명령을 막을 수 있습니다. rm -rf를 시키면 Mod가 막고, 클로드는 막힌 이유를 읽은 뒤 다른 방법을 제안하거나 되묻습니다.

모델에 보내는 요청에도 끼어들 수 있습니다. 짧은 질문은 하이쿠로 보내는 모델 라우터 Mod를 만들면, "안녕"처럼 짧게 보냈을 때 실제로 하이쿠가 답하고 입력창 위 띠에도 하이쿠라고 표시됩니다.

바깥과 연결

Mod는 파일을 읽고 쓰고, 프로그램을 실행하고, 인터넷 요청도 보낼 수 있습니다. 집 기기를 버튼으로 제어하는 것도 같은 방식입니다. 예를 들어 버튼을 누르면 세탁기 서버에서 남은 시간을 받아와 띠에 보여 주는 Mod를 만들 수 있습니다.

소리를 내거나 글을 읽어 주고, 다른 클로드 세션에 메시지를 보내고, 세션 정보(컨텍스트 사용량, 5시간 한도와 주간 한도의 사용 퍼센트, 리셋 시각)를 읽는 것도 됩니다.

다른 사람들이 만든 Mod 예

깃허브에 공개된 Mod 가운데 이런 것들이 있습니다. 모두 개인이 올린 저장소라서 설치 전에 아래 "설치 전 안전 점검"을 먼저 거쳐야 합니다.

• cc-arcade(sezaakgun/cc-arcade): 입력창 위에서 2048, 테트리스, 둠 같은 게임 아홉 개를 합니다.
• Mindful-Claude(halluton/Mindful-Claude): 클로드가 일하는 동안 호흡 안내를 띄웁니다.
• claude-agent-flow(Charlie0113-T/claude-agent-flow): 서브 에이전트를 시키면 옆 패널에서 끝날 때까지 상태를 보여 줍니다.
• devbrothers-mods(devbrother2024/devbrothers-mods): 요청 비용을 택시 요금 미터기처럼 보여 주고, rm -rf 앞에서는 과속 카메라처럼 세워서 묻습니다.

앤트로픽도 공식 샘플 Mod(token-weather, blast-radius, replay-theater)를 anthropics/claude-code-playground 저장소의 claude-code/mods 폴더에 공개해 두었습니다. 지원 없이 있는 그대로 공유되는 예제입니다.

직접 만들기: 사용 한도 미터 Mod

컨텍스트와 사용 한도를 입력창 위 한 줄로 보여 주는 Mod를 만들어 봅니다. 요청은 한 문장이고, 두 번 고쳐서 완성합니다.

1단계. 클로드 코드를 켭니다. 터미널에서는 작업 폴더로 이동해 claude를 입력하고, 데스크톱 앱에서는 Code 탭에서 폴더를 고릅니다. 확인: 클로드 코드 입력창이 보입니다.

2단계. 입력창에 아래 요청을 입력하고 보냅니다.

지금 컨텍스트가 얼마나 찼는지, 5시간이랑 주간 사용 한도를 몇 % 썼는지 입력창 위에 한 줄로 보여 주는 mods 만들어 줘

확인: 요청이 전송됩니다.

3단계. 클로드가 Mod 만들기 스킬을 부르는 것을 기다립니다. 내가 할 동작은 없습니다. 클로드 코드에 들어 있는 plugin-authoring 스킬을 먼저 불러오고, 그 안에서 지금 버전이 지원하는 이벤트와 함수 설명을 읽습니다. 확인: 화면에 스킬을 불러왔다는 줄이 보입니다.

4단계. 클로드가 코드를 쓰고 저장하는 것을 기다립니다. Mod 파일은 ~/.claude/dev-mods/세션ID/Mod이름/ 같은 이 세션 전용 폴더에 저장됩니다. 기본 권한 모드에서는 파일마다 승인 창이 뜨니 하나씩 승인합니다. 확인: 파일이 저장됐다는 안내가 나옵니다.

5단계. "이 세션에서 바로 켤까요?"라는 질문에 Enable for this session을 고릅니다. 확인: 그 턴이 끝나면 입력창 위에 한 줄이 뜹니다.

6단계. 처음 뜬 숫자를 읽습니다. 확인: 컨텍스트 8%, 5시간 16%, 주간 42%처럼 숫자만 나옵니다. 숫자는 내 사용량에 따라 다릅니다.

7단계. 한눈에 안 들어오면 수정을 요청합니다.

숫자만 있으니까 한눈에 안 들어와. 막대랑 색으로 보여 주고, 리셋까지 남은 시간도 같이 띄워 줘

확인: 고친 화면이 바로 다시 뜹니다.

8단계. 클로드가 먼저 알려 주는 한계를 읽습니다. 확인: "남은 시간은 화면이 다시 그려질 때만 계산돼서 가만히 두면 안 줄어든다"는 설명이 나옵니다. Mod는 화면을 스스로 주기적으로 다시 그리지 않기 때문입니다.

9단계. 다시 수정을 요청합니다.

남은 시간이 가만히 두면 안 줄어드는 거, 1분마다 저절로 갱신되게 고쳐 줘

확인: 1분쯤 지나면 남은 시간이 저절로 바뀝니다. 예를 들어 1시간 4분이 1시간 3분이 됩니다. 클로드는 보통 타이머 함수($.clock.every)로 1분마다 다시 그리게 고칩니다.

10단계. 이 Mod가 무엇을 쓰는지 점검합니다. 클로드에게 "이 Mod에 validate 돌려 줘"라고 하거나, 아래 12단계처럼 셸에서 직접 claude plugin validate를 실행합니다. 확인: 세션 정보, 시계, 상태 저장, 화면 그리기만 쓰고 파일도 인터넷도 쓰지 않는다고 나옵니다.

완성된 코드는 세 부분으로 나뉩니다. 세션 정보를 읽는 부분, 1분마다 다시 그리라고 하는 부분, 화면에 한 줄을 그리는 부분입니다.

클로드 코드 Mods로 안 되는 것과 막히는 곳

• 권한 확인 창은 Mod로 바꿀 수 없습니다. 공식 문서도 Mod가 인터페이스 대부분을 바꿀 수 있지만 권한 확인 창은 바꾸지 못한다고 적고 있습니다.
• 에이전트 목록 같은 별도 화면도 못 바꿉니다. 그릴 수 있는 13군데에 들어 있지 않기 때문입니다.
• Mod가 그린 화면은 터미널(에디터 안 터미널 포함), 데스크톱 앱의 Code 탭, VS Code 확장(확장 2.1.299 이상)에서 보입니다. claude -p 같은 비대화형 실행과 클라우드 세션에서는 Mod 코드는 돌지만 화면은 나오지 않습니다. 데스크톱 앱의 WSL 세션에서는 플러그인이 지원되지 않아 Mod가 아예 돌지 않습니다.
• 휴대폰 SSH 앱으로 접속하면 화면은 보이지만 손가락 터치가 마우스 클릭으로 들어오지 않을 수 있습니다. 버튼이 있는 Mod라면 키보드 단축키(hotkey)도 같이 넣어 달라고 하면 됩니다. Mod가 내는 소리는 휴대폰이 아니라 Mod가 도는 컴퓨터에서 납니다.
• 사진(Image 요소)은 터미널에서만 그릴 수 있고, 터미널이 그림 표시를 지원해야 보입니다. 키티(kitty)와 고스티(Ghostty)에서는 그림이 나오지만 맥 기본 터미널, iTerm, VS Code 터미널, 윈도우 터미널에서는 설명 글자만 나오는 경우가 많습니다. 칸마다 색을 칠하는 픽셀 그림(Raster)은 터미널 어디서나 됩니다.
• Mod 함수 하나가 한 번에 10초를 넘기면 클로드 코드가 그 함수를 건너뜁니다.

클로드 코드 Mods 설치 전 안전 점검

가장 중요한 부분입니다. Mod에는 샌드박스가 없고 내 권한으로 돕니다. 공식 문서가 밝히는 Mod의 가능 범위는 이렇습니다.

• 내 계정으로 파일 읽고 쓰기, 프로그램 실행, 인터넷 요청 보내기
• 환경 변수나 설정 파일에 넣어 둔 API 키 읽기
• 내가 보내는 프롬프트와 클로드의 도구 호출을 전부 보고 고치기
• 내가 친 것처럼 프롬프트 보내기, 다른 세션에 메시지 보내기
• 묻지 않고 도구 실행을 허락하기
• 내 요금제나 API 키로 모델 부르기

'묻지 않고 허락하기'를 연습용 파일로 시험해 보면, 원래 파일을 지우기 전에 뜨는 허락 창 없이 파일이 바로 지워집니다. 오토 모드(auto mode)는 다른 모델이 명령을 하나하나 보고 위험하면 막는 방식인데, Mod가 허락한 명령은 그 검사를 건너뜁니다. 회사 관리 설정이 있거나 Team·Enterprise 계정으로 로그인한 경우에는 기본 보호 장치(cc-plugin-sec-default)가 먼저 돌아서, Mod가 deny·ask 규칙을 넘어 허락하지는 못합니다. 개인 계정이나 API 키로 쓰면 이 보호 장치가 없으니 더 조심해야 합니다.

점검은 설치보다 앞에 합니다.

11단계. 남이 만든 Mod는 소스를 내 컴퓨터로 받아 엽니다. 예를 들어 git clone 저장소주소로 받습니다. 확인: hooks/register.js 같은 코드를 눈으로 볼 수 있습니다.

12단계. 받은 폴더에 검사 명령을 돌립니다. 셸에서 Mod 폴더 경로를 붙여 실행합니다.

claude plugin validate ./some-mod

확인: hooks: 줄에는 Mod가 받는 이벤트, calls: 줄에는 Mod가 쓰는 기능 이름이 줄줄이 나옵니다. 휴대폰 앱을 깔 때 사진⁠·위치 권한 목록을 보여 주는 것과 비슷합니다. 코드를 실행하지 않고 읽기만 하므로 이 단계에서는 안전합니다.

13단계. 검사 통과가 안전을 뜻하지 않는다는 점을 기억합니다. 화면이 똑같은 날씨 Mod 두 개를 만들어 시험한 사례가 있습니다. A는 화면만 그리고, B는 몰래 API 키가 있는지 읽고 인터넷 요청을 보냅니다. 둘 다 Validation passed가 떴습니다. 확인: 통과는 파일에 오류가 없다는 뜻이고, 차이는 기능 이름에서 드러납니다. B에만 환경 변수 읽기와 인터넷 요청이 찍힙니다.

calls:와 hooks: 줄에 아래가 보이면 한 번 더 확인합니다.

14단계. $.fs.read, $.fs.write가 있는지 봅니다. 내 계정이 접근할 수 있는 어디서든 파일을 읽고 씁니다. 확인: 있으면 표시해 둡니다.

15단계. $.process.run, $.process.spawn이 있는지 봅니다. 프로그램을 내 이름으로 실행합니다. 확인: 있으면 표시해 둡니다.

16단계. $.http.fetch가 있는지 봅니다. 인터넷 요청을 보냅니다. 확인: 있으면 표시해 둡니다.

17단계. $.env.get, $.settings.read가 있는지 봅니다. API 키가 들어 있을 수 있는 환경 변수와 설정을 읽습니다. 출력의 env reads: 줄에 읽는 변수 이름이 따로 나옵니다. 확인: 있으면 표시해 둡니다.

18단계. $.model.complete가 있는지 봅니다. 내 요금제나 API 키로 모델을 부릅니다. 확인: 있으면 표시해 둡니다.

19단계. hooks: 줄에 tool.call, prompt.submit, tool.check가 있는지 봅니다. tool.call과 prompt.submit은 내 명령과 프롬프트를 다 보고 바꿀 수 있다는 뜻이고, tool.check는 권한 창이 뜨기 전에 허락이나 거부를 할 수 있다는 뜻입니다. 확인: 있으면 표시해 둡니다.

20단계. 표시한 것이 있으면 소스에서 어디로 보내는지 직접 확인합니다. 기능 이름은 무엇을 쓰는지만 알려 주고 어디로 보내는지는 알려 주지 않습니다. 소스에서 $.http.fetch가 부르는 주소를 찾아보거나, 클로드에게 "이 Mod가 무엇을 읽고 어디로 보내는지 알려 줘"라고 물어봅니다. 확인: 보내는 곳이 납득되면 설치로 가고, 납득되지 않으면 설치하지 않습니다.

21단계. 설치할 저장소의 최신 코드가 지난번에 확인한 버전과 같은지 봅니다. 저장소 페이지의 최근 커밋 날짜나 git log -1로 마지막 커밋을 확인합니다. 확인: 내가 검사한 커밋과 같습니다.

놓치기 쉬운 함정도 두 가지 있습니다.

• 샌드박스를 켜도 그 샌드박스는 클로드가 실행하는 Bash 명령만 가둡니다. Mod가 띄운 프로그램은 그 밖에서 돕니다.
• 마켓플레이스의 자동 업데이트를 켜 두면 내가 확인한 파일이 나중에 바뀔 수 있습니다. 공식⁠·앤트로픽 마켓플레이스 말고 제3자 마켓플레이스는 자동 업데이트가 기본으로 꺼져 있으니, 굳이 켜지 않는 편이 안전합니다.

예시로 설치해 보는 마크다운 Mod

순서는 마켓플레이스 추가, 설치, 다시 켜기입니다. 예로 쓸 md-render는 클로드 답의 제목⁠·굵은 글씨⁠·코드⁠·목록에 색을 입히는 Mod입니다. 표와 코드 블록은 원래대로 클로드 코드가 그립니다. 설치 전에 위 11~21단계 점검을 먼저 합니다.

아래 명령은 2026년 10월 기준 저장소 README(deepskyblue86/claude-markdown-mod)와 공식 문서를 따랐습니다. 클로드 코드 대화창 안이라면 같은 명령을 /plugin marketplace add …, /plugin install …로 입력해도 됩니다.

22단계. 깃허브 저장소를 마켓플레이스로 추가합니다. 셸에서 실행합니다.

claude plugin marketplace add deepskyblue86/claude-markdown-mod

확인: Successfully added marketplace: md-render-marketplace처럼 추가됐다는 줄이 나옵니다.

23단계. 플러그인 설치 명령을 실행합니다.

claude plugin install md-render@md-render-marketplace

아무 옵션 없이 설치하면 내 모든 프로젝트에 적용되는 사용자 범위(user scope)로 들어갑니다. --scope project를 주면 그 저장소의 .claude/settings.json에, --scope local을 주면 .claude/settings.local.json에 기록됩니다. 둘 다 지금 폴더가 아니라 그 git 저장소 전체에 적용되니, 저장소 안의 다른 작업에서도 Mod가 켜진다는 점을 알아 둡니다. 확인: Successfully installed plugin으로 시작하는 줄이 나옵니다.

24단계. 클로드 코드를 다시 켭니다. 이미 열어 둔 세션이 있으면 /reload-plugins를 입력해도 됩니다. 확인: 입력창이 다시 열립니다. 셸에서 claude plugin list를 치면 md-render@md-render-marketplace가 범위(Scope)와 상태(Status)와 함께 나옵니다.

25단계. 입력창에 /plugin을 입력합니다. 확인: 탭 아래 흐린 줄에 1 mod active · md-render처럼 켜진 Mod 수와 이름이 뜹니다.

26단계. 같은 글을 클로드가 답하게 해서 비교합니다. Mod를 끈 화면과 켠 화면에서 각각 받아 봅니다. 확인: Mod를 켠 화면에서 제목은 보라색, 굵은 글씨는 주황, 코드는 초록으로 나오고 목록 기호에도 색이 들어갑니다. 답은 쓰는 동안 평범한 글자로 나오다가 다 끝나면 색이 입혀집니다.

한 번만 써 보기와 계속 쓰기

27단계. 한 번만 써 보려면 --plugin-dir 옵션으로 폴더를 지정해 켭니다. 셸에서 claude --plugin-dir ./모드폴더를 실행합니다. 확인: 그 실행에서만 Mod가 켜집니다.

28단계. 계속 쓰려면 마켓플레이스로 설치합니다. 22~25단계와 같습니다. 확인: 클로드 코드를 다시 켜도 /plugin에 Mod가 켜져 있다고 나옵니다.

29단계. 대화 중에 클로드가 만든 Mod는 폴더째 내 자리로 옮겨 둡니다. 그 Mod는 만든 세션에서만 켜지고, 세션 폴더는 cleanupPeriodDays 설정 기간이 지나면 지워집니다. ~/.claude/dev-mods/세션ID/ 아래의 Mod 폴더를 ~/mods/Mod이름처럼 내 폴더로 복사한 뒤 claude --plugin-dir ~/mods/Mod이름으로 켭니다. 확인: 새 세션에서도 Mod가 뜹니다.

이상할 때 끄는 법

30단계. 켜진 Mod를 /plugin으로 확인합니다. Tab 키로 Installed(설치됨) 탭에 가면 목록이 나옵니다. 확인: 지금 켜진 Mod 목록이 보입니다.

31단계. 이상하다 싶은 Mod는 끕니다. 끄는 방법은 세 가지입니다.

• 하나만 끄기: /plugin의 Installed 탭에서 그 Mod를 끄거나 지웁니다.
• 이번 세션만 전부 끄기: claude --safe-mode로 켭니다. 다른 사용자 설정도 함께 꺼집니다.
• 모든 세션에서 내가 설치한 Mod 끄기: ~/.claude/settings.json에 "disableAllHooks": true를 넣습니다. 설정 훅과 사용자 상태 표시줄도 같이 멈춥니다.
• 아예 지우기: 셸에서 플러그인을 지우고, 더 쓸 일이 없으면 마켓플레이스도 지웁니다. 마켓플레이스를 지우면 거기서 설치한 플러그인도 함께 지워집니다.

claude plugin uninstall md-render@md-render-marketplace
claude plugin marketplace remove md-render-marketplace

확인: 그 세션에서 Mod가 그린 화면이 사라집니다. 지운 뒤에는 claude plugin list에 그 이름이 나오지 않습니다. 클로드 코드에 내장된 Mod(/diff 등)는 이 방법들로 꺼지지 않고 /plugin에서 따로 끕니다.

마지막 점검표

• Mod를 만들었을 때 입력창 위에 한 줄이 떴는가
• 남의 Mod는 소스를 열고 claude plugin validate로 기능 이름을 확인한 뒤 설치했는가
• 설치 범위를 project나 local로 줬다면 저장소 전체에서 켜진다는 것을 아는가
• /plugin에서 켜진 Mod를 확인했는가
• 끄는 법(/plugin, --safe-mode, disableAllHooks)을 아는가