클로드 코드 mods (화면과 도구 호출을 바꾸는 플러그인)
클로드 코드 mod는 Claude Code의 화면과 동작을 바꾸는 플러그인으로, JavaScript나 TypeScript 함수가 Claude Code 안에서 실행됩니다. 도구 호출, 프롬프트, 화면 그리기 같은 이벤트를 관찰하거나 바꾸거나 직접 처리하며 샌드박스 없이 사용자 권한으로 실행됩니다.
같은 말:Claude Code modsClaude Mods클로드 모드클로드 코드 모드클로드 코드 mod 만들기plugin-authoringclaude plugin validatehooks.json modules
목차
- 클로드 코드 mod는 화면과 동작을 바꾸는 플러그인입니다
- mod, 설정 훅, 스킬, MCP 서버는 맡는 일이 다릅니다
- mod는 파일 세 개와 register 함수로 이루어집니다
- mod가 실행되는 곳과 화면이 보이는 곳은 다릅니다
- 자동화 담당자가 첫 mod를 만들고 삭제 명령을 막는 과정
- 막는 훅은 실패할 때를 대비해 .catch를 붙입니다
- mod는 샌드박스 없이 사용자 권한으로 실행됩니다
- 비유로 보면 브라우저 확장 프로그램과 닮았습니다
- mod를 시작하는 세 가지 방법
- mod를 켜고 끄는 방법과 조직 관리 설정
- 자주 묻는 질문
- 마무리: mod를 설치하거나 만들기 전에 볼 것
- 참고 자료
설정 훅으로 위험한 명령을 막을 수는 있지만, 작업 중 화면에 확인 버튼을 띄우거나 스피너 옆에 진행 정보를 붙이는 일은 설정 훅이 맡지 못합니다. Claude Code의 화면과 내부 동작 자체를 바꿔야 하기 때문입니다. 이 일을 맡는 것이 mod입니다.
클로드 코드 mod는 Claude Code의 화면과 동작을 바꾸는 플러그인입니다. JavaScript나 TypeScript로 쓴 함수가 Claude Code 안에서 실행되고, 도구 호출, 프롬프트 제출, 화면 그리기 같은 이벤트가 생길 때마다 Claude Code가 그 함수를 부릅니다. Claude Code v2.1.287부터 기본으로 켜져 있으며, 이 버전은 2026년 10월 1일 16시 59분(UTC), 한국 시각으로 10월 2일 새벽에 npm에 배포됐습니다.
클로드 코드 실전
클로드 코드 mod의 훅은
이벤트가 지나는 밸브입니다
Claude가 도구를 쓰려 하면 tool.call 이벤트가 관을 따라 흐르고, mod에 등록한 훅이 중간에서 받습니다.
밸브 방식을 고르고 rm 명령 이벤트를 흘리면 방식마다 결과가 어떻게 다른지 볼 수 있습니다.
Claude가 보낸 이벤트
tool.call Bash
rm notes.txtClaude Code의 기본 동작
밸브를 고르고 이벤트 흘리기 버튼을 누르면 결과가 여기에 나옵니다.
mod 훅의 처리 방식
mod는 Claude Code의 화면과 동작을 바꾸는 플러그인입니다.
훅은 이벤트를 관찰하거나, 바꾸거나, 직접 처리합니다.
하려는 일에 맞는
부품을 고릅니다
공식 비교표를 부품 판으로 옮겼습니다.
하려는 일을 고르면 맞는 부품이 켜집니다.
하려는 일
modhooks/register.js
도구 호출, 프롬프트, 명령, 턴, 화면을 바꿉니다. JavaScript나 TypeScript로 씁니다.
화면에 그릴 수 있습니다.
설정 훅settings.json
진행 여부, 도구 인수와 결과, 추가 맥락을 다룹니다. 스크립트와 설정 파일로 씁니다.
화면에 그릴 수 없습니다.
스킬SKILL.md
Claude가 아는 것과 하는 것을 바꿉니다. 마크다운으로 씁니다.
화면에 그릴 수 없습니다.
MCP 서버외부 프로세스
Claude가 쓸 수 있는 도구를 더합니다. 어떤 언어로든 만듭니다.
화면에 그릴 수 없습니다.
Claude Code 문서의 공식 비교표 기준입니다. 상태줄도 화면 아래에 컨텍스트 사용률 같은 값을 글자로 표시하지만, 창이나 띠에 그리는 일은 mod가 맡습니다.
훅이 도는 곳과
화면이 보이는 곳은 다릅니다
실행 환경을 고르면 두 계량기가 바뀝니다.
차단과 기록 훅은 대부분의 환경에서 실행되지만, 창과 버튼은 일부 환경에서만 보입니다.
편집기 통합 터미널과 JetBrains에서도 훅이 실행됩니다.
창, 띠, 바뀐 행이 모두 보입니다.
2026년 10월 Claude Code Mods 문서 기준입니다. 훅은 Bedrock, Google Cloud Agent Platform, Microsoft Foundry를 포함한 어느 모델 공급자에서도 실행됩니다.
mod를 설치하거나 만들기 전에 이것을 봅니다
- 1
막거나 기록만 할 일은 설정 훅으로 충분하고, 반복 지침은 스킬이, 외부 도구 연결은 MCP가 맡습니다.
- 2
설치 전에 claude plugin validate의 calls 줄에서 파일, 프로세스, 네트워크 호출을 확인합니다.
- 3
차단용 훅에는 .catch를 붙이고, 처리기 안에서 next.called인 경우를 먼저 처리합니다.
- 4
그린 화면은 터미널, 데스크톱 앱, VS Code 확장 2.1.299 이상에서만 보입니다.
클로드 코드 mod는 화면과 동작을 바꾸는 플러그인입니다
공식 문서의 첫 문장은 "A mod is a plugin that changes how Claude Code looks and behaves."입니다. mod는 Claude Code가 보이는 모습과 동작하는 방식을 바꾸는 플러그인이라는 뜻입니다.
플러그인은 스킬, 명령, 에이전트, MCP 서버, 훅을 한 폴더에 묶어 /plugin으로 설치하고 공유하는 Claude Code의 배포 단위입니다. mod도 플러그인이므로 마켓플레이스 설치, 적용 범위, 업데이트 방법이 일반 플러그인과 같고, 플러그인 하나에 mod와 스킬, MCP 서버를 함께 담을 수 있습니다.
용어 두 가지를 먼저 정리합니다. 한국어 공식 문서는 이 기능을 번역하지 않고 mod로 적습니다. 우리말로 '모드'라고 읽으면 권한 모드와 혼동하기 쉽지만 관계없는 기능입니다. 권한 모드는 Claude가 묻지 않고 해도 되는 일의 범위이고, mod는 설치해서 Claude Code를 바꾸는 코드입니다. 또 공식 문서는 mod가 등록하는 함수를 '훅'이라 부르고, 설정 파일에 셸 명령을 적던 기존 방식은 '설정 훅'으로 구분합니다. 이 글도 지금부터 같은 기준으로 씁니다.
mod로 할 수 있는 일은 공식 문서 기준 다섯 가지입니다.
- 새 화면 그리기: 대화 기록(트랜스크립트) 옆의 창(pane)이나 프롬프트 위의 띠(band)에 탭, 버튼, 입력란을 놓습니다.
- 기존 화면 바꾸기: 도구 호출 행, 스피너, Claude가 질문하는 대화 상자처럼 Claude Code가 원래 그리는 요소를 교체합니다.
- 도구 호출에 개입하기: 사용자에게 묻는 동안 도구 호출을 보류하거나, 도구를 실행하지 않고 대신 답하거나, 요청을 다른 모델로 보냅니다.
- 즉시 실행되는 명령 추가: Claude의 응답 차례(턴)를 기다리지 않고 바로 실행되는
/명령을 만듭니다. - 훅끼리 값 공유: 같은 파일 안의 훅은 변수를 함께 쓰므로, 한 훅이 기록한 값을 다른 훅이 화면에 표시합니다.
mod, 설정 훅, 스킬, MCP 서버는 맡는 일이 다릅니다
네 기능은 겹치는 부분이 있어 처음에는 무엇을 고를지 판단하기 어렵습니다. 공식 문서는 설정 훅, 스킬, 상태줄, MCP 서버가 Claude Code 바깥에서 동작하고 mod는 안에서 실행된다고 구분합니다. 공식 비교표를 옮기면 다음과 같습니다.
| 항목 | mod | 설정 훅 | 스킬 | MCP 서버 |
|---|---|---|---|---|
| 실행 위치와 파일 | Claude Code 안에서 실행 | settings.json | SKILL.md | 외부 프로세스 |
| 바꿀 수 있는 것 | 도구 호출, 프롬프트, 명령, 턴, 화면 | 진행 여부, 도구 인수와 결과, 추가 맥락 | Claude가 아는 것과 하는 것 | Claude가 쓸 수 있는 도구 |
| 화면에 그리기 | 됨 | 안 됨 | 안 됨 | 안 됨 |
| 작성 언어 | JavaScript, TypeScript | 스크립트와 settings.json | 마크다운 | 어떤 언어든 가능 |
| 고르는 경우 | 창이나 명령이 필요하거나 이벤트를 다시 써야 할 때 | 이미 있는 스크립트로 차단, 허용, 기록만 할 때 | 같은 지침을 반복해 붙여 넣을 때 | Claude가 외부 시스템에 접근해야 할 때 |
상태줄도 화면 아래에 컨텍스트 사용률 같은 값을 글자로 표시할 수 있습니다. 창이나 띠에 그리는 일은 mod가 맡습니다.
판단 순서는 간단합니다. 막거나 기록만 하면 되는 일은 설정 훅으로, 반복 지침은 스킬로, 외부 도구 연결은 MCP로 하고, 화면에 무언가를 띄우거나 Claude Code의 기존 동작을 바꿔야 할 때 mod를 검토합니다.
mod는 파일 세 개와 register 함수로 이루어집니다
가장 작은 mod는 파일 세 개입니다.
first-mod/
├── .claude-plugin/
│ └── plugin.json
└── hooks/
├── hooks.json
└── register.jsClaude Code가 이 파일들을 어떤 순서로 읽어 mod를 실행하는지 따라가면 다음과 같습니다.
- plugin.json: 이름, 버전, 설명을 적습니다. mod 전용 필드는 없습니다.
- hooks.json:
modules배열에 훅 모듈 경로를 하나 적습니다. - register 함수: mod가 로드될 때 한 번 실행되어
on으로 이벤트를 등록합니다. - 훅 실행: 등록한 훅이 이벤트가 생길 때마다
($, e, next)인수를 받아 호출됩니다.
훅 모듈은 .js, .mjs, .cjs, .jsx, .ts, .mts, .cts, .tsx 파일을 쓸 수 있고, hooks.json의 hooks 아래에 설정 훅을 함께 둘 수도 있습니다.
다음은 공식 문서 예제에 한국어 주석을 붙인 코드입니다. Claude가 도구를 쓸 때마다 횟수를 기록하고, 작업 중 스피너 옆에 그 값을 표시합니다.
// 두 훅이 함께 쓰는 값
let calls = 0
// mod가 로드될 때 Claude Code가 한 번 호출하는 함수
export function register(on) {
// Claude가 도구를 쓰려 할 때마다 실행
on('tool.call', async ($, e, next) => {
calls += 1
// 화면을 다시 그려 달라고 요청해 새 값이 보이게 함
$.ui.invalidate('ui.render')
// 도구는 원래대로 실행
return next(e)
})
// Claude Code가 스피너를 그릴 때마다 실행
on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
// 원래 스피너를 유지하고 단어 뒤에 횟수만 덧붙임
return next({ ...e, props: { ...e.props, suffix: ' (tool calls: ' + calls + ')' } })
})
}모든 훅은 인수 세 개를 받습니다. $는 화면 그리기, 명령 등록, 파일 읽기 같은 외부 작업을 요청하는 mods API입니다. e는 도구 이름과 인수처럼 이벤트에 담긴 데이터이고 바꿀 수 없게 고정되어 있어서, 바꾸려면 복사본을 만들어 next에 넘깁니다. next(e)는 이벤트를 다음 핸들러와 Claude Code의 기본 동작으로 넘깁니다. { component: 'Spinner' }처럼 훅이 반응할 대상을 좁히는 두 번째 인수는 matcher라고 부릅니다.
훅이 이벤트를 처리하는 방식은 세 가지입니다.
| 방식 | 코드 | 예 |
|---|---|---|
| 관찰(Observe) | 기록만 하고 next(e)를 그대로 반환 | 도구 호출 횟수 기록 |
| 재작성(Rewrite) | 바꾼 복사본으로 next를 호출 | 스피너 문구에 횟수 추가 |
| 직접 처리(Answer) | next를 부르지 않고 결과를 반환 | 명령을 거부하고 이유를 Claude에게 전달 |
그리기, 명령 추가, 모델 호출, 파일 읽기, 프로세스 시작, 네트워크 요청은 모두 mods API로만 할 수 있습니다. 통로가 하나뿐이라서 Claude Code는 mod를 실행하지 않고도 그 mod가 무엇을 요청하는지 나열할 수 있습니다. 설치 전 점검에서 이 기능을 씁니다.
mod가 실행되는 곳과 화면이 보이는 곳은 다릅니다
훅은 플러그인을 불러오는 대부분의 세션에서 실행되지만, mod가 그린 화면이 보이는 곳은 그보다 좁습니다. 화면 없이 동작하는 차단과 기록은 대부분의 환경에서 쓸 수 있지만, 창과 버튼은 일부 환경에서만 보입니다.
| 실행 환경 | 훅 실행(차단, 기록, 명령) | 그린 내용 표시(창, 띠, 바뀐 행) |
|---|---|---|
| 터미널의 claude(편집기 통합 터미널, JetBrains 포함) | 됨 | 됨 |
| 데스크톱 앱 Code 탭 | 됨 | 터미널 전용 요소 제외 |
| 데스크톱 앱 WSL 세션 | 안 됨 | 안 됨 |
| VS Code 확장 채팅 패널 | 됨 | 확장 2.1.299 이상 |
| claude -p와 Agent SDK | 됨 | 안 됨 |
| claude.ai와 모바일 앱의 Remote Control | 내 컴퓨터 세션에서 실행 | 내 컴퓨터 터미널에 표시 |
| 클라우드 세션 | 클라우드로 전달되는 플러그인이면 실행 | 안 됨 |
VS Code 확장에서 기능 플래그를 받지 않는 세션(Amazon Bedrock 등)은 확장이 2.1.304 이상이어야 mod가 화면을 그립니다. 훅은 Bedrock, Google Cloud Agent Platform, Microsoft Foundry를 포함한 어느 모델 공급자에서도 실행됩니다.
화면을 그리는 mod를 만들 때는 그릴 수 없는 환경도 생각합니다. claude -p처럼 화면이 없는 곳에서는 트랜스크립트의 한 줄이나 명령의 텍스트 응답으로 같은 정보를 대신 보여 주도록 만듭니다.
자동화 담당자가 첫 mod를 만들고 삭제 명령을 막는 과정
사내 업무 자동화를 맡은 현우 씨를 예로 들어 보겠습니다. 현우 씨는 Claude Code에 파일 정리 작업을 자주 맡기면서 두 가지가 아쉬웠습니다. 작업 중에 Claude가 도구를 몇 번이나 쓰는지 보고 싶었고, 정리 폴더에서 파일을 지우는 명령은 확실히 막고 싶었습니다. 현우 씨는 macOS의 새 빈 폴더 mod-practice에서 시작합니다. Linux나 WSL에서도 같은 순서로 따라 할 수 있습니다.
1단계: 버전을 확인하고 파일 세 개 만들기
터미널에서 claude --version을 입력해 2.1.287 이상인지 확인합니다. 데스크톱 앱은 Code 탭 로컬 세션에서 /status를 입력해 Claude Code 행의 버전이 2.1.286 이상인지 봅니다. 버전이 맞으면 폴더 두 개를 만듭니다. Windows PowerShell에서는 New-Item -ItemType Directory -Force first-mod\.claude-plugin, first-mod\hooks를 씁니다.
mkdir -p first-mod/.claude-plugin first-mod/hooksfirst-mod/.claude-plugin/plugin.json과 first-mod/hooks/hooks.json을 다음 내용으로 저장합니다. author를 빼도 동작하지만 점검 단계에서 작성자 정보가 없다는 경고가 나옵니다.
{
"name": "first-mod",
"version": "0.1.0",
"description": "Counts Claude's tool calls, shows the count beside the spinner, and adds a /tally command",
"author": { "name": "Your Name" }
}{
"description": "The first-mod hooks module",
"modules": ["./register.js"]
}first-mod/hooks/register.js에는 앞의 예제에 /tally 명령을 더한 코드를 저장합니다.
let calls = 0
export function register(on) {
// 세션이 시작될 때 /tally 명령을 등록
on('session.start', async ($, e, next) => {
await $.command.register({ name: 'tally', description: 'Show how many tool calls Claude has made' })
return next(e)
})
// 도구 호출마다 횟수를 기록하고 화면을 다시 그리게 함
on('tool.call', async ($, e, next) => {
calls += 1
$.ui.invalidate('ui.render')
return next(e)
})
// /tally를 입력했을 때만 실행되어 횟수를 출력
on('command.run', { command: 'tally' }, async () => {
return { text: 'Claude has made ' + calls + ' tool calls since this mod loaded' }
})
// 스피너 문구 뒤에 횟수를 덧붙임
on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
return next({ ...e, props: { ...e.props, suffix: ' (tool calls: ' + calls + ')' } })
})
}2단계: 실행하지 않고 점검한 뒤 한 세션에 불러오기
claude plugin validate는 mod를 실행하지 않고 처리하는 이벤트(hooks:)와 Claude Code에 요청하는 작업(calls:)을 나열합니다. 이어서 claude -p "/tally" --plugin-dir ./first-mod로 대화 없이 명령만 실행해 mod가 로드되는지 봅니다. 준이아빠블로그가 2026년 10월 6일 macOS의 Claude Code v2.1.291에서 실행한 결과는 다음과 같았습니다.
$ claude plugin validate ./first-mod
❯ ./register.js hooks: session.start, tool.call, command.run{command=tally}, ui.render{component=Spinner}
❯ ./register.js gating hook without .catch: tool.call
❯ ./register.js calls: $.command.register, $.ui.invalidate
✔ Validation passed
$ claude -p "/tally" --plugin-dir ./first-mod
first-mod: Claude has made 0 tool calls since this mod loaded위 출력은 2026년 10월 6일 v2.1.291에서 실행한 결과이고, 여기서 볼 줄은 세 가지입니다.
calls: 줄에는 $.command.register와 $.ui.invalidate 두 개뿐입니다. 파일, 프로세스, 네트워크를 다루는 호출이 없으니 이 mod는 화면과 명령만 다룬다는 사실을 실행 전에 확인한 셈입니다. gating hook without .catch 줄은 tool.call 훅에 오류 처리기가 없다는 안내이고, 이 mod는 아무것도 막지 않으므로 그대로 둬도 됩니다. /tally 결과 앞에 first-mod:가 붙고 0이 나오면 정상으로 로드된 것입니다.
--plugin-dir로 불러온 폴더는 감시되어, 파일을 고쳐 저장하면 다시 로드됩니다. 다시 로드되면 register가 새로 실행되어 calls도 0부터 다시 기록됩니다. claude --plugin-dir ./first-mod로 대화형 세션을 열고 도구를 여러 번 쓰는 작업을 요청하면 스피너 문구 뒤에 횟수가 붙습니다.
3단계: 삭제 명령을 막는 mod로 바꾸기
이번에는 직접 처리 방식의 훅을 만듭니다. 연습 폴더에 guard-mod를 같은 구조로 만들고, plugin.json은 first-mod의 파일을 복사해 name만 guard-mod로 바꿉니다. hooks.json은 {"modules":["./register.js"]}만 있어도 됩니다. register.js는 다음과 같습니다.
export function register(on) {
// Bash 도구 호출만 검사
on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
if (/(^|\s)rm\s/.test(e.command)) {
// 트랜스크립트에 흐린 줄로 기록
$.ui.log('guard-mod blocked: ' + e.command)
// next를 부르지 않으므로 명령은 실행되지 않음. Claude는 이 문장을 도구 결과로 읽음
return { deny: 'Deleting files is not allowed in this folder. Tell the user the file was kept.' }
}
return next(e)
})
}시험용 폴더 work에 notes.txt를 만들고 그 폴더에서 실행합니다. --allowedTools "Bash(rm:*)"는 mod가 없다면 rm 명령이 승인 없이 실행되도록 허용하는 옵션입니다. 이 실행은 모델을 한 번 호출하므로 플랜 사용량이 조금 차감됩니다.
mkdir work && echo hello > work/notes.txt && cd work
claude -p "Run this exact bash command: rm notes.txt" --plugin-dir ../guard-mod --allowedTools "Bash(rm:*)"
ls$ claude -p "Run this exact bash command: rm notes.txt" ...
이 폴더에서는 파일 삭제가 차단되어 있어서 notes.txt는 지워지지 않고 그대로 남아 있습니다.
$ ls
notes.txt2026년 10월 6일 v2.1.291에서 실행한 결과이고, 명령의 옵션 부분은 줄였습니다.
허용 규칙이 있어도 mod의 tool.call 훅이 명령을 거부했고, ls 결과에도 notes.txt가 남았습니다. Claude의 답만 보고 "막았다"고 판단하지 않고, 파일이 실제로 남아 있는지 직접 확인하는 것이 이 단계의 핵심입니다.
막는 훅은 실패할 때를 대비해 .catch를 붙입니다
현우 씨의 guard-mod에는 함정이 하나 남아 있습니다. .catch가 없는 훅이 next를 부르기 전에 오류를 내거나 시간 한도를 넘기면, Claude Code는 그 훅을 건너뛰고 다음 핸들러를 실행합니다. 막으려던 명령이 그대로 실행될 수 있다는 뜻입니다. 시간 한도는 다음과 같습니다.
| 한도 | 값 | 알아 둘 점 |
|---|---|---|
| 이벤트 하나당 훅 실행 | 10초 | next와 mods API 호출 시간은 제외합니다 |
| prompt.edit 훅 | 50밀리초 | 다른 훅보다 한도가 훨씬 짧습니다 |
| .catch 처리기 | 1초 | 실패한 훅을 뒤처리하는 시간입니다 |
| $.process.run 기본값 | 30초 | 최대 10분까지 늘릴 수 있습니다 |
표의 값은 Mods reference 문서 기준입니다(CLI와 데스크톱 v2.1.290, VS Code 확장 v2.1.299).
실패하면 막는 쪽으로 동작하게 하려면 검사 부분을 guard 함수로 분리하고 .catch 처리기를 붙입니다. 공식 예시처럼 guard가 이미 next를 부른 뒤에 실패한 경우를 먼저 처리해야, 정상 통과한 명령까지 거부하는 일이 생기지 않습니다.
// guard는 직접 작성한 차단 함수
on('tool.call', { tool: 'Bash' }, guard).catch(async ($, e, next) => {
// guard가 이미 next를 부른 뒤 실패했다면 그 결과를 그대로 둔다
if (next.called) return next(e)
// 검사 도중 실패했다면 명령을 실행하지 않고 거부한다
return { deny: 'The command guard failed, so this command was not run: ' + next.error.kind }
})v2.1.290부터 claude plugin validate는 차단 지점의 훅마다 .catch가 있는지 함께 보여 줍니다. .catch를 붙인 뒤 다시 점검했을 때 gating hook without .catch 줄이 사라지면 훅이 실패해도 명령을 거부하는 구조가 된 것입니다. 건너뛴 훅은 my-mod: tool.call hook skipped: threw Error: boom 같은 형식으로 로그에 남습니다.
정리하면, 삭제를 막는 tool.call 훅이 next를 부르기 전에 오류를 냈는데 .catch가 없다면, Claude Code는 그 훅을 건너뛰고 다음 핸들러를 실행합니다. 명령이 실행될 수 있으므로 막는 용도의 훅에는 .catch를 붙여 실패해도 거부하게 만듭니다.
mod는 샌드박스 없이 사용자 권한으로 실행됩니다
mod는 내 계정 권한으로 실행되는 코드입니다. 공식 문서가 밝힌 접근 범위는 다음과 같습니다.
- 사용자 계정이 접근할 수 있는 모든 파일을 읽고 쓰며, 프로그램을 실행하고 네트워크 요청을 보냅니다.
- 환경 변수와 설정 파일에 들어 있는 API 키를 읽습니다.
- 모든 프롬프트와 도구 호출을 보고, 다시 쓰고, 사용자가 입력한 것처럼 프롬프트를 보내고, 다른 세션에 메시지를 보냅니다.
- 확인을 묻기 전에 도구 호출을 승인합니다.
- 사용자의 플랜이나 API 키로 모델을 호출해 사용량을 씁니다.
네 번째 항목에는 조건이 있습니다. 관리 설정이 있는 컴퓨터이거나 Team, Enterprise 계정으로 /login한 세션에서는 기본적으로 mod의 승인이 ask 규칙과 PreToolUse 설정 훅을 넘지 못합니다. 둘 다 없는 개인 환경에서만 mod가 그런 호출까지 승인할 수 있습니다. 반대로 mod가 바꾸지 못하는 것도 있습니다. 권한 프롬프트에 표시되는 내용은 mod가 고칠 수 없고, 프롬프트가 뜨기 전에 승인하거나 거부할 수만 있습니다.
권한을 막는 설정이 mod에도 그대로 적용된다고 생각하기 쉬운데, 실제로는 그렇지 않은 곳이 있습니다.
| 흔한 오해 | 실제 |
|---|---|
| 샌드박스를 켜면 mod도 격리된다 | 샌드박스가 격리하는 것은 Claude가 실행하는 Bash 명령입니다. mod가 시작한 프로세스는 샌드박스 밖에서 실행됩니다 |
| Read(.env)를 거부 규칙에 넣으면 mod도 .env를 못 읽는다 | 권한 규칙과 PreToolUse는 Claude의 도구 호출에만 적용됩니다. mod는 $.fs.read로 같은 파일을 읽을 수 있습니다 |
| WebFetch를 막으면 mod도 인터넷에 접속하지 못한다 | mod는 $.http.fetch로 네트워크 요청을 보낼 수 있습니다. 그래서 설치 전 validate의 calls 줄이 중요합니다 |
설치하기 전에는 claude plugin validate <폴더>로 mod가 무엇을 하는지 먼저 봅니다. calls: 줄에 $.process(프로그램 실행), $.fs(파일 접근), $.http(네트워크 요청)가 보이면 그 호출이 왜 필요한지 코드에서 찾아봅니다. 환경 변수나 $.state를 쓰는 mod는 env reads:, state reads: 줄도 함께 나옵니다.
비유로 보면 브라우저 확장 프로그램과 닮았습니다
mod는 웹 브라우저의 확장 프로그램과 닮았습니다. 확장 프로그램은 브라우저 자체를 다시 만들지 않고 스토어에서 설치해, 도구 모음에 버튼을 더하고 페이지 요청을 막거나 바꿉니다.
| 클로드 코드 mod | 브라우저 확장 프로그램 |
|---|---|
| Claude Code에 설치하는 mod | 브라우저에 설치하는 확장 프로그램 |
| 마켓플레이스에서 /plugin install | 확장 프로그램 스토어에서 설치 |
| 창(pane)과 띠(band) | 도구 모음 버튼과 옆 패널 |
| tool.call 훅의 거부 | 광고 차단기가 페이지 요청을 막는 일 |
| validate의 hooks와 calls 줄 | 설치 전에 보는 권한 목록 |
비유가 맞지 않는 곳도 있습니다. 브라우저는 확장 프로그램마다 허용한 권한 안에서만 동작하게 막지만, mod는 샌드박스 없이 사용자 계정 권한 그대로 실행됩니다. 또 calls 목록은 스토어가 보여 주지 않으며 설치 전에 validate를 직접 실행해야 볼 수 있습니다.
비유에서 가져갈 점은 하나입니다. 확장 프로그램을 설치하기 전에 권한 목록을 보듯이, mod를 설치하기 전에는 validate 출력을 봅니다. 다만 mod에는 권한을 나눠 막는 장치가 없으므로 이 목록을 더 꼼꼼히 읽어야 합니다.
mod를 시작하는 세 가지 방법
이미 들어 있는 내장 mod
Claude Code의 일부 기능은 그 자체가 mod입니다. /plugin의 Installed 탭에서 Built-in 아래에 보입니다.
/plugin에 보이는 이름 | 하는 일 |
|---|---|
cc-plugin-agents-md | 프로젝트의 AGENTS.md를 지침으로 불러옵니다 |
cc-plugin-diff | /diff를 맡아 변경 내용 창을 그립니다 |
cc-plugin-plugin-authoring | mod 작성용 plugin-authoring 스킬을 제공합니다 |
cc-plugin-sec-default | 조직이 관리하는 항목을 사용자 mod로부터 보호합니다. 끌 수 없습니다 |
cc-plugin-telemetry | Claude Code와 내장 mod의 분석 기록을 전송합니다 |
cc-plugin-you-should-know | 긴 작업 중 보조 에이전트가 놓친 점을 프롬프트 위에 알립니다. 기본은 꺼져 있습니다 |
cc-plugin-you-should-know는 /plugin enable cc-plugin-you-should-know@builtin으로 켭니다. diff, agents-md, sec-default, telemetry의 소스는 anthropics/claude-code 저장소의 mods/ 폴더에 공개되어 있어 실제 mod 코드를 참고하기 좋습니다.
Claude에게 만들어 달라고 요청하기
대화형 세션에서 원하는 기능을 설명하면 Claude가 내장 plugin-authoring 스킬로 mod를 작성합니다. 공식 문서의 예시는 make a mod that shows the current git branch above the prompt이고, /plugin-authoring으로 스킬을 직접 불러올 수도 있습니다.
- Claude는
~/.claude/dev-mods/<세션 ID>/<mod 이름>/폴더에 파일을 만듭니다. default와 acceptEdits 권한 모드에서는 보호된 경로라 파일마다 승인을 묻습니다. - 첫 파일을 저장하면 핫 리로드(코드가 바뀔 때마다 다시 불러오기)를 켤지 묻습니다. Enable for this session을 고르면 mod가 턴이 끝날 때 로드되고 이후 바뀔 때마다 다시 로드됩니다. Not now를 고르면 다음 세션을 시작할 때 로드됩니다.
- 이렇게 만든 mod는 만든 세션에서만 로드되고, 세션 폴더가
cleanupPeriodDays보다 오래되면 지워집니다. 계속 쓰려면 폴더를 복사해claude --plugin-dir <경로>로 불러오거나 마켓플레이스에 올립니다.
claude -p나 dontAsk 모드처럼 승인할 사람이 없는 세션, 신뢰하지 않은 작업 폴더, mod가 꺼진 세션에서는 Claude가 작성한 mod가 로드되지 않습니다.
마켓플레이스에서 설치하기
mod는 일반 플러그인처럼 <플러그인>@<마켓플레이스>로 설치합니다. 세션 안에서는 /plugin install <플러그인>@<마켓플레이스>, 셸에서는 claude plugin install <플러그인>@<마켓플레이스>를 씁니다. 셸에서 설치했다면 열려 있는 세션에서 /reload-plugins를 실행해야 바로 반영됩니다. 앤트로픽은 claude-code-playground 저장소의 claude-code/mods에 샘플 mod 세 개를 지원 없이 공유하고 있습니다.
| 샘플 | 하는 일 |
|---|---|
token-weather | 프롬프트 위에 컨텍스트 창 사용량 예보를 그립니다 |
blast-radius | rm -rf나 강제 푸시 같은 위험한 명령을 보류하고, 무엇이 바뀌는지 보여 준 뒤 진행과 취소 버튼을 띄웁니다 |
replay-theater | 직전 턴에서 Claude가 고친 파일을 단계별로 다시 보는 /replay 명령을 더합니다 |
설치한 사본은 버전별로 캐시되므로, 직접 고치는 중인 mod는 --plugin-dir로 불러옵니다. 고친 내용을 설치본에 반영하려면 버전을 올려 다시 설치합니다. claude-로 시작하는 이름처럼 Anthropic 이름으로 보이는 플러그인 이름은 validate에서 실패합니다.
mod를 켜고 끄는 방법과 조직 관리 설정
mod는 기본으로 켜져 있습니다. 끄는 범위에 따라 방법이 다릅니다.
| 끄는 범위 | 방법 |
|---|---|
| mod 하나 | /plugin의 Installed 탭에서 비활성화하거나 제거 |
| 설치한 모든 mod, 이번 세션만 | claude --safe-mode 또는 --bare로 시작 |
| 직접 설치한 모든 mod, 모든 세션 | ~/.claude/settings.json에 "disableAllHooks": true (설정 훅과 사용자 상태줄도 중지) |
세 방법 모두 내장 mod는 멈추지 않습니다. 얼리 액세스 때 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS를 설정했다면 지웁니다. v2.1.287부터 이 값은 무시되어 0으로 둬도 mod가 꺼지지 않습니다. 지금 로드된 mod는 /plugin을 열었을 때 탭 아래 흐린 줄에 1 mod active처럼 개수와 이름으로 표시되고, 내장 mod는 이 줄에서 빠집니다.
관리 설정이 있는 컴퓨터이거나 Team, Enterprise로 로그인한 경우 Claude Code는 사용자 mod보다 먼저 sec-default 가드를 불러옵니다. 가드는 사용자 mod가 관리형 훅, 시스템 프롬프트, 관리형 CLAUDE.md, 관리형 MCP 서버의 도구를 바꾸지 못하게 막고, deny와 ask 규칙, PreToolUse가 막은 호출을 승인하지 못하게 합니다. 관리자가 allowModsToOverrideDenyRules를 켜면 deny 규칙의 호출도 승인할 수 있습니다. 가드는 관리 설정을 읽지 못하면 모든 사용자 mod를 거부해 안전한 쪽으로 멈춥니다.
| 원하는 결과 | 관리형 설정 |
|---|---|
| 사용자 mod만 막고 설정 훅은 유지 | pluginConfigs의 cc-plugin-sec-default@builtin 아래 allowManagedModsOnly |
| 조직 mod만 허용 | allowManagedModsOnly와 조직 mod 설치. 사용자 설정 훅까지 막으려면 allowManagedHooksOnly |
| 승인한 마켓플레이스의 mod만 허용 | 마켓플레이스 제한과 disableSideloadFlags: true (--plugin-dir과 세션 중 Claude가 쓴 mod 거부) |
| 모든 mod와 훅 중지 | disableAllHooks |
| 모두 허용하되 조직 mod가 검사 | prependPlugins에 조직 mod와 sec-default@builtin 등록 |
자주 묻는 질문
코딩을 몰라도 mod를 쓸 수 있나요?
설치해서 쓰는 일은 일반 플러그인과 같아 코딩 지식이 필요하지 않습니다. 만들 때도 원하는 기능을 말로 설명하면 Claude가 plugin-authoring 스킬로 코드를 작성합니다. 다만 mod는 내 권한으로 실행되는 코드이므로 설치 전에 claude plugin validate 출력의 calls: 줄을 보고, 파일이나 프로세스, 네트워크 접근이 있으면 그 이유를 Claude에게 물어봅니다.
이미 만든 설정 훅을 mod로 옮겨야 하나요?
옮길 필요는 없습니다. 명령을 막거나 기록하는 일은 설정 훅으로 충분하고, 설정 훅과 mod는 함께 동작합니다. 화면에 확인 버튼을 띄우거나, 도구를 실행하지 않고 대신 답하거나, 즉시 실행되는 명령이 필요할 때 mod를 검토합니다.
VS Code 확장이나 claude -p에서도 mod가 동작하나요?
훅은 두 환경 모두에서 실행됩니다. mod가 그린 창과 띠는 VS Code 확장 2.1.299 이상의 채팅 패널에서 보이고, claude -p와 Agent SDK에서는 보이지 않습니다. 데스크톱 앱의 WSL 세션은 플러그인을 지원하지 않아 훅도 실행되지 않습니다.
설치한 mod를 모두 끄려면 어떻게 하나요?
이번 세션만 끄려면 claude --safe-mode로 시작하고, 모든 세션에서 끄려면 ~/.claude/settings.json에 "disableAllHooks": true를 넣습니다. 두 방법 모두 내장 mod는 멈추지 않으며, disableAllHooks는 설정 훅과 사용자 상태줄도 함께 멈춥니다.
마무리: mod를 설치하거나 만들기 전에 볼 것
- 정말 mod가 필요한지: 막거나 기록만 하는 일은 설정 훅으로 충분하고, 반복 지침은 스킬이, 외부 도구 연결은 MCP가 맡습니다.
- 설치 전 점검:
claude plugin validate의calls:줄에서 파일, 프로세스, 네트워크 호출을 확인합니다. - 막는 훅의 실패: 차단용 훅에는
.catch를 붙이고,next.called를 먼저 처리합니다. - 보이는 곳: 그린 화면은 터미널, 데스크톱 앱, VS Code 확장 2.1.299 이상에서만 보입니다.
업무 폴더를 건드리지 않고 지금 해 볼 수 있는 일은 세 가지입니다.
claude --version으로 2.1.287 이상인지 확인하고 새 폴더mod-practice를 만듭니다.- first-mod를 만들어
claude plugin validate의hooks:와calls:줄을 읽고/tally가 0을 출력하는지 확인합니다. - guard-mod로
rm notes.txt가 거부되는지 보고,ls로 파일이 남았는지 직접 확인합니다.
참고 자료

제대로 이해했는지 한 문제로 확인해 볼까요?
답을 고르면 바로 풀이가 나와요.
클로드 코드 mod, 설정 훅, 스킬, MCP 서버 가운데 mod만 할 수 있는 일은 무엇일까요?
예제나 확인 질문을 직접 시도한 뒤 완료 표시해요. 더 연습할 내용이 남으면 표시하지 않고 다음 글을 읽어도 됩니다. 완료 버튼은 이해도를 채점하지 않으며 잘못 표시하면 취소할 수 있어요.

