Mods — Claude Code 동작 확장
Mod는 JavaScript 또는 TypeScript 이벤트 핸들러를 플러그인으로 배포해 Claude Code 안에서 실행하는 확장입니다. 도구 호출과 프롬프트를 관찰하거나 바꾸고, 명령·도구를 추가하거나 터미널 인터페이스를 그릴 수 있습니다. 단순한 지침을 제공하는 Skill이나 외부 도구를 연결하는 MCP 서버보다 Claude Code의 동작에 더 깊이 개입합니다.
Settings Hooks와 무엇이 다른가
이름은 비슷하지만 실행 방식과 목적이 다릅니다.
| 구분 | Settings Hooks | Mods |
|---|---|---|
| 정의 위치 | 설정 파일의 hooks | 플러그인 안의 JavaScript·TypeScript 핸들러 |
| 실행 방식 | 셸 명령, HTTP 요청 또는 프롬프트 실행 | Claude Code 프로세스 안에서 이벤트 핸들러 실행 |
| 주된 용도 | 기존 스크립트로 이벤트를 기록·차단·보정 | UI, 새 명령·도구, 프롬프트·도구 호출의 세밀한 변경 |
| 선택 기준 | 스크립트로 충분한 자동화 | 앱 안의 UI나 더 깊은 동작 확장이 필요할 때 |
Mods가 추가됐다고 기존 Settings Hooks가 사라지는 것은 아닙니다. 셸 스크립트로 처리할 수 있는 작업이라면 기존 Hooks가 더 단순할 수 있습니다.
플러그인 안의 파일 구조
Mod는 별도 설치 형식이 아니라 플러그인입니다. 작은 예시는 다음처럼 구성됩니다.
first-mod/
├── .claude-plugin/
│ └── plugin.json
└── hooks/
├── hooks.json
└── register.js
hooks.json은 핸들러 모듈을 가리키고, register.js는 이벤트별 함수를 등록합니다. 이벤트 핸들러는 이벤트를 그대로 다음 단계로 넘기거나(next(e)), 내용을 바꾸거나, 기본 동작을 대신 처리할 수 있습니다. 구현에 필요한 세부 명세는 빠르게 바뀔 수 있으므로 공식 개요, 이벤트, API, 테스트를 기준으로 확인하세요.
Mods는 사용자 권한으로 실행된다
Mod는 설치한 사용자의 권한으로 실행되며 Bash 샌드박스 안에 격리되지 않습니다. 사용자가 접근 가능한 파일을 읽고 쓸 수 있고, 환경 변수·설정 파일의 비밀값과 대화 프롬프트·도구 호출에 접근할 수 있습니다. 프로세스 실행이나 네트워크 요청, 프롬프트·도구 호출 변경, 모델 사용량 발생도 가능합니다.
따라서 마켓플레이스에 있다는 이유만으로 안전하다고 가정하지 마세요. 작성자와 배포 출처를 확인하고, 설치 전 플러그인 디렉터리에서 다음 명령으로 Mod가 다루는 이벤트와 API 호출을 살펴봅니다.
claude plugin validate ./some-mod
출력의 hooks:와 calls: 항목을 확인하고, 실제 핸들러 소스도 검토하세요. 검토가 끝나지 않은 코드는 개인 정보나 자격 증명이 있는 환경에서 실행하지 않는 편이 안전합니다. 이 검증은 정적 검토를 돕는 수단이지, 코드가 안전하다는 보증은 아닙니다.
특히 다음을 확인합니다.
- 어떤 이벤트에서 실행되는가
- 파일·프로세스·네트워크 API를 호출하는가
- 프롬프트나 도구 호출을 수정·대체하거나 사용자 대신 승인하는가
- 모델 호출로 사용량이나 비용을 발생시키는가
- 코드가 실제 배포 출처의 코드와 일치하는가
Claude가 실행하는 Bash 명령에 샌드박스를 적용해도 Mod가 직접 시작한 프로세스는 그 경계 밖에서 실행될 수 있습니다. Bash 샌드박스나 권한 설정을 Mod 코드의 안전장치로 간주하지 마세요.
조직의 권한 정책도 Mod 자체의 코드 실행 권한과 구분해야 합니다. 관리형 정책의 보호 기능은 Claude가 요청하는 도구 호출을 통제하지만, Mod가 직접 호출하는 파일·프로세스 API까지 대신 제한하지는 않습니다. 따라서 PreToolUse나 권한 규칙이 있다고 해서 검토하지 않은 Mod를 안전하게 실행할 수 있는 것은 아닙니다. 정책별 동작과 적용 조건은 공식 관리 문서를 확인하세요.
다만 관리형 설정을 사용하거나 Team·Enterprise 계정으로 로그인한 기본 환경에서는 Mod의 승인 코드가 ask 규칙이나 PreToolUse 훅을 우회해 도구 호출을 통과시키지 못합니다. 이런 보호가 적용되지 않는 환경에서는 Mod가 해당 호출을 승인할 수 있습니다. deny 규칙과 Mod의 상호작용은 별도 조건이 있으므로, 이를 포함해 조직의 정책 구성을 확인하세요.
활성 상태와 비활성화
공식 문서 기준으로 Mods는 기본 활성화되어 있습니다. CLI는 v2.1.287 이상, Claude Desktop의 Code 탭은 앱에 포함된 Claude Code v2.1.286 이상에서 지원됩니다. 사용 중인 환경과 버전을 확인한 뒤 적용하세요.
- 현재 세션에서 로드된 Mod는
/plugin의 Installed 탭에서 확인합니다. - 개별 Mod는 해당 플러그인을 비활성화하거나 제거합니다.
- 사용자 설치 Mods 전체를 한 세션에서 끄려면
claude --safe-mode를 사용할 수 있습니다. 이 옵션은 다른 사용자 지정 기능도 함께 끕니다. - 모든 세션에서 사용자 설치 Mods를 끄려면
disableAllHooks설정을 사용할 수 있습니다. Settings Hooks와 사용자 상태 표시줄도 함께 꺼지며, 기본 제공(built-in) Mods에는 적용되지 않습니다.
기본 제공 Mods는 /plugin의 Installed 탭에서 별도로 확인할 수 있습니다. 사용자 설치 Mods와 다르게, --safe-mode나 disableAllHooks만으로 기본 제공 Mods까지 끌 수 있는 것은 아닙니다.
관리형 조직 환경에는 별도 정책이 있습니다. 관리자는 조직의 managed settings로 허용할 Mod 범위를 제어할 수 있습니다. 조직 정책을 구성할 때는 공식 Mods 관리 문서를 확인하세요.
다음 단계
다음 챕터: 마켓플레이스 운영 →
이 챕터를 완료하셨나요?
학습 진도를 체크하여 나의 로드맵 달성률을 높여보세요.