핵심 요약
Anthropic이 2026년 10월 1일 Claude Code의 **모드(mod)**를 공개했습니다. 모드는 Claude Code 내부에서 실행되는 JavaScript나 TypeScript 함수로 이루어진 플러그인입니다. 공식 기능 출시를 기다리지 않고도 프롬프트와 도구 호출을 바꾸거나, Claude Code 화면에 나만의 창과 버튼을 추가할 수 있습니다. 직접 작성해도 되고, 원하는 동작을 설명하면 Claude Code가 모드를 만들어 줍니다.
주요 기능
-
이벤트를 가로채 지켜보거나, 바꾸거나, 대신 처리
기존 훅(hook)은 settings.json에 등록한 셸 명령이나 HTTP 요청을 Claude Code 바깥에서 실행하는 방식이라, 할 수 있는 일이 도구 호출 허용과 차단, 인자 수정 정도로 제한됐습니다. 모드의 함수는 Claude Code 안에서 실행되며, 이벤트가 처리되기 전에 호출되어 다음 동작을 직접 정합니다. 그대로 통과시키며 기록하거나(observe), 내용을 바꾸거나(rewrite), 기본 동작 대신 직접 처리할(answer) 수 있습니다. 발표문은 모델에 전달되기 전 프롬프트 다시 쓰기, 도구 호출의 차단과 수정, 재시도, 권한 요청 승인과 거부, 도구 출력에서 비밀 정보(secret)를 가린 뒤 Claude에 전달하기를 예로 듭니다. 문서에서는 모드의 함수를 “hook”, settings.json 방식을 “settings hook”으로 구분해 부릅니다.
-
나만의 화면 요소 추가
훅, 스킬, MCP 서버는 화면에 무언가를 그릴 수 없었습니다. 모드는 대화 기록 옆 창(pane)이나 프롬프트 위 띠(band)를 만들고, 그 안에 탭, 버튼, 입력 칸을 넣을 수 있습니다. 문서는 요청마다 컨텍스트가 얼마나 찼는지 그래프로 보여 주는 창을 예로 듭니다.
-
Claude Code의 기존 화면 바꾸기
도구 호출 행, 진행 표시(spinner), Claude가 질문할 때 뜨는 대화 상자처럼 Claude Code가 직접 그리는 부분도 바꾸거나 다시 꾸밀 수 있습니다. 문서 예제는 도구 호출 횟수를 세어 진행 표시 옆에
Thinking · tool calls: 3…처럼 보여 줍니다. 단, 권한 확인 창은 바꿀 수 없습니다. -
Claude 응답 없이 바로 실행되는 명령
모드로
/command를 추가하면 Claude의 응답 차례를 거치지 않고 바로 함수가 실행됩니다. Claude가 작업 중일 때도 쓸 수 있습니다. -
Claude에게 만들어 달라고 요청
Claude Code 세션에서 원하는 동작을 설명하면 Claude가 모드를 작성합니다. 이를 위한
plugin-authoring스킬이 내장 플러그인으로 함께 들어 있습니다. -
플러그인으로 배포하고 설치
모드는 플러그인 안에 담겨 배포되므로, 기존 플러그인과 같은 방식으로 마켓플레이스에서 설치합니다. 세션 안에서는
/plugin install token-chart@your-org, 셸에서는claude plugin install token-chart@your-org형태로 실행합니다. 세션이 열려 있는 동안 셸에서 설치했다면/reload-plugins로 불러옵니다.
알아두면 좋은 점
- v2.1.287 이상 필요 — 모드 기능은 기본으로 켜져 있습니다.
claude --version으로 버전을 확인합니다. 사전 체험 기간에CLAUDE_CODE_ENABLE_FUNCTION_HOOKS를 설정했다면 v2.1.287부터는 무시되므로 지웁니다. - 동작 범위는 실행 환경마다 다름 — 터미널의
claude(편집기 내장 터미널, JetBrains 플러그인 포함)와 Desktop 앱 Code 탭에서는 이벤트 처리와 화면 요소가 모두 적용됩니다. VS Code 확장의 채팅 패널,claude -p, Agent SDK, 클라우드 세션에서는 이벤트 처리만 동작하고 화면 요소는 나타나지 않습니다. Desktop 앱의 WSL 세션에서는 플러그인을 쓸 수 없어 모드도 동작하지 않습니다. - 샌드박스 없이 사용자 권한으로 실행 — 발표문은 “Mods run with the same access to your machine as Claude Code itself. They aren’t sandboxed”라고 밝힙니다. 모드는 파일 읽기와 쓰기, 프로세스 실행, 네트워크 요청이 가능하고, 환경 변수의 API 키를 읽거나 도구 호출을 사용자 확인 없이 승인할 수도 있습니다. 신뢰하는 작성자와 마켓플레이스의 모드만 설치합니다.
- 설치 전에 동작 확인 — 플러그인 파일을 받은 뒤
claude plugin validate ./some-mod를 실행하면, 출력의hooks:와calls:줄에 모드가 처리하는 이벤트와 요청하는 작업(파일 읽기, 네트워크 요청 등)이 표시됩니다. 모드를 실행하지 않고 확인할 수 있습니다. - 끄는 방법 — 모드 하나는
/plugin의 Installed 탭에서 끄거나 제거합니다. 한 세션만 모두 끄려면--safe-mode로 시작하고, 모든 세션에서 끄려면~/.claude/settings.json에"disableAllHooks": true를 설정합니다. 이 경우 settings hook과 사용자 지정 상태 표시줄도 함께 멈춥니다. - 조직 관리 — 관리자는 관리형 설정(managed settings)으로 어떤 모드를 실행할지 정할 수 있습니다. 내장 모드
sec-default는 사용자가 설치한 모드로부터 조직이 관리하는 설정과 모드를 보호합니다. - 내장 모드 —
/diff화면,AGENTS.md불러오기처럼 Claude Code의 일부 기능도 모드로 만들어져 있으며,/plugin의 Installed 탭 Built-in 항목에서 볼 수 있습니다.diff,agents-md,sec-default,telemetry의 소스는 anthropics/claude-code 저장소의 mods 디렉터리에 공개되어 있습니다. - 공식 문서 — 만드는 법, 화면 그리기, 이벤트 처리, 테스트, 조직 관리 방법은 Mods overview 문서에서 이어집니다.