SpyBara
Go Premium

plugins/mods/overview.md 2026-10-01 23:59 UTC to 2026-10-02 04:57 UTC

This page contains 52 additions and 32 deletions.

2026
Thu 1 23:59 Fri 2 04:57

Mods 개요

mod를 사용하여 Claude Code에 창, 명령, 도구 호출 규칙을 추가합니다. mod가 할 수 있는 것, mod를 만들거나 설치하는 방법, mod가 실행되는 위치를 확인합니다.

mod는 Claude Code의 모양과 동작을 변경하는 플러그인입니다. JavaScript 또는 TypeScript 이벤트 핸들러로 구성됩니다. Claude Code는 도구 호출, 제출된 프롬프트, 인터페이스의 일부가 그려지는 것과 같은 이벤트가 발생할 때 하나를 호출하며, 핸들러는 이벤트를 감시하거나, 변경하거나, 인수할 수 있습니다. mod를 사용하여 각 요청 후 컨텍스트가 얼마나 찼는지 차트로 표시하는 창과 같이 Claude Code에 자신만의 기능을 추가합니다. mod의 파일과 완전한 예제는 mod의 작동 방식을 참조합니다.

mod가 할 수 있는 것

설정 hooks, skills, 상태 줄, MCP 서버는 Claude Code 외부에서 작동합니다. 각각 스크립트를 실행하거나 Claude에 텍스트 또는 도구를 제공합니다. mod는 Claude Code 내부에서 실행되므로 다음을 수행할 수 있습니다:

  • 사용할 수 있는 인터페이스 그리기: 대화 옆의 창 또는 프롬프트 위의 밴드, 탭, 버튼, 텍스트 필드 포함. 인터페이스에 그리기를 참조합니다.
  • Claude Code 자체 인터페이스 다시 그리기: Claude Code가 자체적으로 그리는 부분(예: 도구 호출의 행, 스피너 또는 Claude가 질문하는 대화)을 교체하거나 다시 스타일링합니다. Claude Code가 이미 그린 것 변경을 참조합니다.
  • 도구 호출 또는 요청에 개입: 예를 들어, 도구 호출을 유지하면서 사용자에게 질문하고, 도구를 실행하지 않고 답변하거나, 한 요청을 다른 모델로 보냅니다. 도구 호출 보호 또는 변경 및 턴 따르기를 참조합니다.
  • 명령에서 자신의 코드 실행: Claude 턴 없이 즉시 실행되는 /command, Claude가 작업 중일 때도 실행됩니다. 명령 또는 도구 추가를 참조합니다.
  • hooks 간 데이터 공유: mod의 hooks는 파일의 변수를 공유하므로 한 hook이 기록하는 것을 다른 hook이 표시할 수 있습니다. 예를 들어, 한 hook은 도구 호출을 세면서 다른 hook은 스피너 옆에 개수를 표시하거나, 한 hook은 각 요청의 토큰 사용량을 읽으면서 다른 hook은 창에서 차트로 표시할 수 있습니다. 이벤트에 반응을 참조합니다.

Mods는 Claude Code CLI 및 Claude Desktop 앱의 Code 탭에서 작동합니다. VS Code 확장, claude -p, 클라우드 세션과 같은 다른 위치에서의 동작을 이해하려면 mods가 실행되는 위치를 참조합니다. 설정 hook, skill 또는 MCP 서버가 이미 필요한 것을 수행하면, mod를 작성하기 전에 비교합니다. 조직의 mods를 관리하려면 조직의 mods 관리를 참조합니다.

mod 가져오기

다음 세 가지 방법 중 하나로 mod를 시작할 수 있습니다:

mod 설치 또는 업데이트

mod는 마켓플레이스에서 플러그인으로 설치됩니다. 플러그인의 이름, @, 마켓플레이스의 이름을 제공합니다. 이 예제는 your-org라는 마켓플레이스에서 token-chart라는 플러그인을 설치합니다:

  • Claude Code 세션에서 /plugin install token-chart@your-org를 실행합니다.
  • 셸에서 claude plugin install token-chart@your-org를 실행합니다.

플러그인 설치는 마켓플레이스, 범위, VS Code 확장 및 Desktop 앱, 플러그인 업데이트 유지를 다룹니다. 이는 mod를 포함하는 플러그인에 변경 없이 적용됩니다.

세션이 열려 있는 동안 셸에서 mod를 설치하거나 업데이트하면, 해당 세션에서 /reload-plugins를 실행하여 로드합니다. 그렇지 않으면 Claude Code를 다음에 시작할 때 로드됩니다.

샘플 mod 사용해 보기

Anthropic은 claude-code-playground 저장소의 claude-code/mods 디렉터리에서 샘플 mods를 공유합니다. 각 샘플은 완전한 플러그인이며, README에 제작 방법이 설명되어 있습니다. 이 저장소는 샘플을 있는 그대로 공유하며 지원은 제공하지 않습니다.

  • token-weather: 프롬프트 위에 컨텍스트 윈도우의 예보를 그립니다
  • blast-radius: rm -rf나 강제 푸시와 같은 위험한 셸 명령을 보류하고, 그 명령이 무엇을 변경할지 보여 주며 계속하거나 취소하는 버튼을 제공합니다
  • replay-theater: 마지막 턴에서 Claude가 수행한 파일 편집을 단계별로 살펴보는 /replay 명령을 추가합니다

샘플 mod는 사용자의 권한으로 실행됩니다. 로드하기 전에 mod가 무엇을 하는지 확인하려면 훅과 호출 목록을 확인합니다.

사용해 보려면 저장소를 복제하고 --plugin-dir로 mod의 디렉터리를 한 세션 동안 로드합니다. mod가 로드되었는지 확인하려면 세션이 로드한 mods를 확인합니다.

계속 사용하려면 복제본의 claude-code/mods 디렉터리를 마켓플레이스로 추가한 다음 claude-code-playground-mods에서 mod를 설치합니다. 마켓플레이스는 복제본을 가리키므로, 복제본을 이동하거나 삭제하면 mod가 더 이상 로드되지 않습니다.

모드를 신뢰할지 결정하기

모드는 Claude Code 내에서 사용자의 권한으로 실행되는 코드입니다. 신뢰하는 작성자 및 마켓플레이스에서만 모드를 설치하십시오.

모드가 접근할 수 있는 것

모드는 사용자의 권한으로 실행되므로, 설치하기 전에 어떤 것에 접근할 수 있는지 알아야 합니다. 모드가 로드되면 다음을 수행할 수 있습니다:

  • 사용자로서 머신에서 작동: 사용자 계정이 접근할 수 있는 모든 곳에서 파일을 읽고 쓰기, 프로그램 시작, 네트워크 요청 수행
  • 비밀 정보 읽기: 환경 변수 및 설정 파일(API 키 포함)
  • 세션 확인: 사용자가 보내는 모든 프롬프트 및 Claude가 수행하는 모든 도구 호출 확인
  • 세션 변경: 프롬프트 또는 도구 호출 재작성, 사용자가 입력한 것처럼 프롬프트 제출, 다른 세션으로 메시지 전송
  • 사용자에게 묻지 않고 작동: 사용자에게 묻기 전에 도구 호출 승인
  • 사용량 소비: 플랜 또는 API 키의 모델 호출

모드는 샌드박스 안에서 실행되지 않습니다. 샌드박싱을 켜면 샌드박스는 Claude가 실행하는 Bash 명령을 격리하지만, 모드가 시작하는 프로세스는 샌드박스 외부에서 실행됩니다.

도구 호출을 승인하는 모드는 ask 규칙이 프롬프트하는 호출이나 사용자의 PreToolUse 훅이 차단한 호출을 승인할 수 있습니다. 훅으로 권한 확장하기에서는 이러한 모드가 승인할 수 있는 것(예: deny 규칙이 거부하는 호출을 승인할 수 있는 경우 포함)을 나열합니다.

모드는 Claude Code 인터페이스의 대부분을 다시 스타일링할 수 있지만, 권한 프롬프트는 변경할 수 없습니다. 프롬프트가 표시하는 내용을 변경할 수 없습니다.

설치하기 전에 모드가 수행하는 작업 나열하기

모드를 설치하기 전에, 모드가 훅하는 이벤트와 파일 읽기 또는 네트워크 요청 수행과 같이 Claude Code에 요청하는 작업을 실행하지 않고 나열할 수 있습니다. 먼저 플러그인의 파일을 가져옵니다(예: 저장소 복제). 그런 다음 셸에서 플러그인 디렉터리에 대해 claude plugin validate를 실행합니다:

claude plugin validate ./some-mod

출력의 hooks: 및 calls: 줄은 모드가 처리하는 이벤트와 Claude Code에 요청하는 작업을 나열합니다. 모드가 수행할 수 있는 작업 검토하기에서는 출력과 확인할 호출을 보여줍니다.

mods 켜기 또는 끄기

Mods는 Claude Code v2.1.287 이상이 필요하며 기본적으로 켜져 있습니다. 셸에서 claude --version을 실행하여 확인하고, 더 오래된 경우 Claude Code를 업데이트합니다.

mods를 끄려면 중지할 개수와 기간을 선택합니다. 다시 켜려면 동일한 변경을 취소합니다:

  • 하나의 mod: /plugin의 설치됨 탭에서 플러그인을 비활성화하거나 제거합니다.
  • 모든 설치된 mod, 한 세션 동안: --safe-mode로 Claude Code를 시작합니다. 이는 다른 사용자 정의도 제외합니다.
  • 설치한 모든 mod, 모든 세션에서: ~/.claude/settings.json에서 "disableAllHooks": true를 설정합니다. 설정 hooks 및 사용자 정의 상태 줄도 중지됩니다. 조직이 관리하는 것은 계속 실행됩니다.

조직을 통해 Claude Code를 사용하면 관리자가 로드되는 mods를 제한할 수도 있습니다. 관리자는 사용자 설치 mods가 로드되지 않도록 중지에서 시작합니다.

disableAllHooks와 조직의 allowManagedModsOnly는 mod를 중지하되 해당 플러그인의 나머지 부분은 그대로 둡니다. 플러그인은 설치된 상태로 유지되며, 플러그인의 스킬, 명령, 에이전트, MCP 서버는 로드됩니다. 다른 설정과 플래그는 더 넓은 범위에 영향을 줍니다. disableAllHooks 및 allowManagedHooksOnly에서 실행되는 항목에서 각 설정이 플러그인과 해당 설정 훅에 어떤 영향을 주는지 확인할 수 있습니다.

mods가 로드될 수 있는지 확인하려면 mods가 로드될 수 있는지 확인을 참조합니다.

세션이 로드한 mods 보기

터미널 세션이 로드한 mods를 보려면 Claude Code 프롬프트에서 /plugin을 실행합니다. 탭 아래의 흐린 줄은 개수와 이름(예: 1 mod active · first-mod)을 제공합니다. 설치한 mod가 거기에 이름이 없으면 mod가 아무것도 하지 않는 이유 찾기를 참조합니다.

mod의 작동 방식

mod는 훅이라고 불리는 이벤트 핸들러를 코드로 등록하는 플러그인입니다. Claude Code는 Claude가 도구를 호출하거나 스피너가 그려질 때와 같이 해당 이벤트가 발생하면 훅을 실행합니다. 작은 mod는 세 개의 파일로 구성됩니다.

first-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

다음은 완전한 register.js입니다. Claude가 수행하는 도구 호출 횟수를 세고, Claude가 작업하는 동안 Thinking · tool calls: 3…처럼 스피너 옆에 그 횟수를 표시합니다.

// The count, shared by the two hooks below
let calls = 0

// Claude Code calls this once when the mod loads
export function register(on) {
  // Runs each time Claude is about to use a tool
  on('tool.call', async ($, e, next) => {
    calls += 1
    // Ask Claude Code to draw the interface again, so the new count shows
    $.ui.invalidate('ui.render')
    // Let the tool run as usual
    return next(e)
  })

  // Runs each time Claude Code draws the spinner
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    // Keep Claude Code's spinner, with the count added after its word
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

이 파일은 두 개의 훅을 등록하며, 둘 다 맨 위의 calls 변수를 사용합니다.

  • tool.call 훅은 Claude가 도구를 사용하려고 할 때마다 실행됩니다. calls에 1을 더하고, Claude Code에 인터페이스를 다시 그리도록 요청한 다음, 도구가 평소대로 실행되도록 합니다.
  • ui.render 훅은 Claude Code가 스피너를 그릴 때마다 실행됩니다. Claude Code의 스피너를 그대로 유지하고 단어 뒤에 횟수를 추가합니다.

이 녹화 영상은 mod가 작동하는 모습을 보여줍니다. 프롬프트 상자 위의 스피너 줄을 확인하세요. Claude가 디렉토리를 나열하고 두 파일을 읽는 동안 Thinking · tool calls: 1…, 이어서 2…, 3…이 표시됩니다.