이 문서는 Claude Code의 기능을 확장하는 플러그인 시스템인 Mods의 개념, 작동 원리, 활용 방법 및 보안 정책을 상세히 설명합니다.

1. 개요 및 핵심 개념

Mods는 Claude Code의 인터페이스와 동작을 직접 수정하거나 제어할 수 있는 JavaScript 또는 TypeScript 기반의 이벤트 핸들러입니다. 기존의 설정 훅(Settings Hooks), 스킬(Skills), MCP(Model Context Protocol) 서버가 외부 프로세스나 스크립트 형태로 작동하는 것과 달리, Mods는 Claude Code 내부 엔진과 직접 상호작용합니다.

2. 핵심 방법론: 훅(Hooks) 기반 이벤트 처리

Mods의 핵심은 이벤트 기반 프로그래밍 모델입니다. 개발자는 register(on) 함수를 통해 특정 이벤트에 핸들러를 등록하며, Claude Code는 이벤트 발생 시 이를 호출합니다.

• 이벤트 핸들링: on(event, handler)를 통해 tool.call, ui.render 등 다양한 시스템 이벤트를 구독합니다.
• 제어 흐름: 핸들러는 next(e)를 통해 기본 동작을 수행하거나, 이벤트를 중단·재작성·관찰할 수 있습니다.
  • 예: tool.call 발생 시 $calls += 1$로 상태를 갱신하고, $.ui.invalidate('ui.render')를 호출하여 인터페이스를 강제로 갱신합니다.
• 상태 공유: 동일한 플러그인 파일 내의 훅들은 전역 변수(예: $let calls = 0$)를 통해 상태를 공유하여, 한 훅에서 기록한 데이터를 다른 훅이 표시하는 등의 상호작용이 가능합니다.

3. 주요 기능 및 기술적 범위

• 인터페이스 재구성: $.ui.invalidate와 같은 API를 통해 프롬프트 상단, 트랜스크립트 옆의 창, 상태바 등 Claude Code의 UI 요소를 동적으로 다시 그릴 수 있습니다.
• 도구 호출 및 명령 개입: tool.call 이벤트에 개입하여 특정 도구 사용을 보류하거나 권한을 재정의하고, Claude의 턴 없이도 직접 실행 가능한 /command를 정의할 수 있습니다.
• 권한 및 보안: Mods는 사용자의 권한으로 실행되므로 파일 시스템 접근, 네트워크 요청, 환경 변수 읽기 등이 가능합니다.
  • 보안 검증: 설치 전 claude plugin validate 명령을 통해 해당 mod가 사용하는 훅과 호출 목록을 명시적으로 검토할 수 있습니다.
  • 격리 수준: 샌드박싱(Sandboxing)은 Bash 명령만 격리하므로, Mod 자체의 프로세스는 사용자의 시스템 권한을 온전히 상속받습니다.

4. 구성 요소

하나의 Mod 플러그인은 통상적으로 다음 구조를 가집니다:

• plugin.json: 플러그인 매니페스트.
• hooks.json: 실행할 훅 모듈 파일 경로 정의.
• register.js: 실제 이벤트 핸들링 로직이 담긴 코드.

5. 비교 분석

Mods는 다른 확장 기법들과 다음 측면에서 차별화됩니다.

• 설정 훅: 스크립트 기반의 단순 차단/로그 기록에 최적화됨.
• 스킬: 정적인 지침 전달에 최적화됨.
• MCP 서버: 외부 시스템 도구 제공에 최적화됨.
• Mods: 실시간 UI 렌더링, 도구 호출의 상세 제어, 복합적인 사용자 경험(UX) 개선이 필요한 경우에 적합함.

6. 결론

Mods는 Claude Code 사용자가 자신의 작업 흐름에 맞춰 인터페이스와 자동화 로직을 최적화할 수 있도록 지원하는 고수준의 플러그인 프레임워크입니다. 사용자는 안전한 출처의 플러그인만을 설치해야 하며, 조직 관리자는 managed settings를 통해 mod의 실행 범위를 제어하여 보안 정책을 수립할 수 있습니다.