breakinglog
Claude Code 2.1.287 이상을 쓰고 있다면, 이제 설정 파일이나 셸 훅을 넘어서 Claude Code 자체의 동작과 화면을 작은 플러그인 코드로 바꿀 수 있습니다. 10월 1일 공개된 Claude Code Mods 가이드에 따르면 Mod는 JavaScript 또는 TypeScript 모듈로 이벤트를 관찰하고, 입력을 바꾸고, 도구 호출을 막거나 직접 답하며, 터미널 UI까지 그릴 수 있습니다. Mods는 해당 버전부터 기본으로 켜져 있어 별도 실험 플래그를 활성화할 필요도 없습니다.
가장 빠른 첫 성공은 API를 외워 직접 코드를 쓰는 것이 아닙니다. Claude Code에게 만들고 싶은 Mod를 자연어로 설명하면 현재 세션에서 hot reload할 임시 Mod를 만들 수 있고, 수정할 때마다 재시작 없이 결과를 볼 수 있습니다.
먼저 버전만 확인하고, Claude에게 Mod를 하나 만들어 달라고 하세요
터미널에서 현재 버전을 확인합니다. 공식 가이드의 요구 조건은 2.1.287 이상입니다.
claude --version조건을 만족한다면 작업할 폴더에서 claude를 실행한 뒤 Claude Code 채팅 입력창에 아래처럼 요청할 수 있습니다. 다음 문장은 공식 예제를 그대로 옮긴 것이 아니라, 같은 API 경로를 확인하기 위한 입력 예시입니다.
Claude Code Mod를 하나 만들어줘. 이름은 context-meter로 해줘.
매 turn.complete 뒤 현재 컨텍스트 사용률을 읽고,
프롬프트 바로 위에 "Context 42%"처럼 한 줄로 표시해줘.
이번 세션에서 hot reload로 바로 확인할 수 있게 하고,
기존 프로젝트 파일은 수정하지 마.공식 가이드의 이 경로에서는 Claude Code가 hot reload 사용 여부를 한 번 묻고, 허용하면 만든 Mod가 같은 세션에서 바로 로드됩니다. 정상이라면 다음 턴이 끝난 뒤 프롬프트 위에 컨텍스트 사용률을 보여주는 한 줄이 나타나고, 표시 문구나 임계값을 다시 요청해 바꾸면 실행 중인 세션에서 갱신됩니다.
이 빠른 경로에서 만들어진 폴더는 세션용이며 나중에 정리될 수 있습니다. 계속 쓸 기능이라면 만들어진 폴더를 별도 위치에 보존하고 일반 Claude Code 플러그인처럼 설치하는 단계로 넘어가야 합니다.
Mod는 기존 settings hook과 무엇이 다른가요?
둘 다 이벤트에 반응하지만 실행 방식이 다릅니다. 기존 settings hook은 이벤트마다 셸 명령을 실행하고 표준 입력과 출력으로 JSON을 주고받는 방식인 반면, Mod는 세션 안에서 한 번 로드된 모듈이 계속 살아 있으면서 상태를 유지하고 UI와 Claude Code 기능을 호출할 수 있습니다.
| 구분 | settings hook | Mod |
|---|---|---|
| 실행 방식 | 이벤트마다 외부 셸 명령 실행 | 세션에 로드된 JavaScript/TypeScript 모듈 |
| 상태 유지 | 별도 저장을 직접 설계 | $.state로 세션 상태 유지 |
| 동작 변경 | 주로 입력/출력 JSON으로 허용 여부 판단 | 이벤트 관찰, 입력 재작성, 직접 응답 가능 |
| 화면 | Claude Code UI 자체를 그리지 않음 | 프롬프트 위 영역이나 pane 같은 UI 렌더 가능 |
Mod의 훅은 미들웨어처럼 이어집니다. 이벤트를 그대로 넘기고 결과만 관찰할 수도 있고, 다음 단계가 볼 입력을 바꿀 수도 있으며, next를 호출하지 않고 도구 호출을 거부하거나 직접 결과를 돌려줄 수도 있습니다. 공식 샘플인 Token Weather, Blast Radius, Replay Theater가 각각 상태 표시, 위험 명령 확인, 편집 내역 재생이라는 서로 다른 형태를 보여주는 이유가 이 차이입니다.
계속 쓸 Mod는 플러그인 폴더로 보존합니다
지속적으로 쓸 Mod의 기본 구조는 일반 Claude Code 플러그인과 같습니다. .claude-plugin/plugin.json이 플러그인을 설명하고, hooks/hooks.json이 실행할 모듈을 가리키며, 모듈은 register(on, options)를 내보냅니다.
context-meter/
├── .claude-plugin/
│ └── plugin.json
└── hooks/
├── hooks.json
└── context-meter.mjs개발 중인 폴더를 바로 읽히려면 터미널에서 다음처럼 시작할 수 있습니다. 저장할 때마다 모듈이 hot reload되므로, UI나 훅 동작을 고칠 때 세션을 계속 새로 띄울 필요가 없습니다.
claude --plugin-dir ./context-meter배포 전에는 claude plugin validate ./context-meter로 manifest와 훅, 상태 선언을 검사할 수 있고, 테스트 파일을 만들었다면 claude plugin test ./context-meter로 실제 Claude Code 런타임을 대상으로 테스트할 수 있습니다. 검증이 통과하면 Validation passed가 표시되고, 테스트는 pass/fail 요약을 돌려줍니다. 두 명령 모두 현재 설치된 Claude Code 런타임을 사용하므로 배포하려는 버전에서 다시 확인하는 것이 좋습니다.
hot reload를 쓴다면 상태는 모듈 변수보다 $.state에 둡니다
Mod 파일을 저장하면 모듈이 새로 로드되기 때문에 단순한 모듈 전역 변수는 초기화될 수 있습니다. 공식 Token Weather 예시는 컨텍스트 사용 기록을 $.state에 저장해 reload 뒤에도 같은 세션의 기록이 이어지도록 만듭니다.
또한 Claude Code가 Mod를 로드할 때 현재 빌드의 타입 선언을 .claude-plugin/types/ 아래에 기록합니다. Mods API는 릴리스 사이에 바뀔 수 있다고 공식 문서가 명시하므로, 블로그의 오래된 코드 조각보다 현재 설치된 Claude Code가 생성한 타입을 기준으로 이벤트와 $ 메서드를 확인하는 편이 안전합니다.
설치할 때는 일반 패키지처럼 신뢰 여부를 확인해야 합니다
Mod 모듈 자체에는 DOM이나 Node API가 직접 열려 있지 않고 파일, 프로세스, HTTP, UI 같은 기능은 Claude Code가 제공하는 $ 인터페이스를 통해 사용합니다. 그렇다고 설치한 Mod를 단순한 테마처럼 취급해도 된다는 뜻은 아닙니다. 공식 가이드도 Mod가 사용자 컴퓨터의 Claude Code 안에서 실행되는 코드이므로 저장소를 먼저 읽고 신뢰하는 제작자의 것만 설치하라고 안내합니다.
Anthropic의 공개 Claude Code 저장소에는 실제 내장 Mod 소스도 있습니다. /diff, AGENTS.md 지원 같은 기능이 같은 Mod 구조로 구현돼 있어, 처음부터 API를 추측하기보다 현재 버전에서 동작하는 코드를 참고하기 좋습니다.
정리하면 단순히 도구 호출을 허용하거나 거부하는 규칙만 필요하다면 기존 permission rule이나 settings hook이 더 직접적입니다. 반대로 세션 상태를 계속 추적하거나, 이벤트 사이의 동작을 바꾸거나, Claude Code 화면에 전용 표시와 pane을 추가하려는 경우가 Mods를 쓸 이유입니다.
대표 이미지는 Mod가 Claude Code 이벤트를 관찰하고, 명령을 가로막고, 화면 요소를 추가하는 확장 구조를 설명하기 위해 Breakinglog가 생성한 편집용 3D 개념 이미지입니다. 실제 Claude Code UI나 Anthropic 공식 이미지가 아닙니다.
