SpyBara
Go Premium

plugins/mods/overview.md 2026-09-30 23:00 UTC to 2026-10-01 21:02 UTC

This page contains 269 additions and 0 deletions.

2026
Thu 1 21:02

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를 다음에 시작할 때 로드됩니다.

모드를 신뢰할지 결정하기

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

모드가 접근할 수 있는 것

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

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

도구 호출을 승인하는 모드는 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가 로드되지 않도록 중지에서 시작합니다.

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

세션이 로드한 mods 보기

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

mod의 작동 방식

mod는 hooks라고 불리는 이벤트 핸들러를 등록하는 플러그인입니다. Claude Code는 Claude가 도구를 호출하거나 스피너가 그려질 때와 같은 이벤트가 발생할 때 hook을 실행합니다. 작은 mod는 세 개의 파일을 가집니다:

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

이것은 완전한 register.js입니다. Claude가 수행하는 도구 호출을 세고 Claude가 작업하는 동안 스피너 옆에 개수를 표시합니다(예: Thinking · tool calls: 3…).

// 아래의 두 hooks로 공유되는 개수
let calls = 0

// Claude Code는 mod가 로드될 때 이것을 한 번 호출합니다
export function register(on) {
  // Claude가 도구를 사용하려고 할 때마다 실행됩니다
  on('tool.call', async ($, e, next) => {
    calls += 1
    // Claude Code에 인터페이스를 다시 그리도록 요청하여 새 개수가 표시되도록 합니다
    $.ui.invalidate('ui.render')
    // 도구가 평소대로 실행되도록 합니다
    return next(e)
  })

  // Claude Code가 스피너를 그릴 때마다 실행됩니다
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    // Claude Code의 스피너를 유지하고 단어 뒤에 개수를 추가합니다
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

파일은 두 개의 hooks를 등록하고 둘 다 맨 위의 calls 변수를 사용합니다:

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

이 기록은 mod가 작동하는 것을 보여줍니다. 프롬프트 상자 위의 스피너 줄을 보세요. Claude가 디렉토리를 나열하고 두 파일을 읽는 동안 Thinking · tool calls: 1…, 그 다음 2…, 그 다음 3…을 읽습니다.