SpyBara
Go Premium

plugins/mods/overview.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 56 additions and 56 deletions.

2026
Thu 1 23:59 Fri 2 22:59 Tue 6 23:59 Thu 8 22:58 Wed 14 22:58 Thu 15 23:58 Mon 19 23:58 Tue 20 23:00 Thu 22 22:58 Fri 23 22:59

Mods 개요

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

mod는 Claude Code의 모양과 동작을 바꾸는 플러그인입니다. mod는 JavaScript 또는 TypeScript 이벤트 핸들러로 구성됩니다. 도구 호출, 프롬프트 제출, 인터페이스 일부의 렌더링과 같은 이벤트가 발생하면 Claude Code가 핸들러를 호출하며, 핸들러는 해당 이벤트를 관찰하거나, 변경하거나, 직접 처리할 수 있습니다. mod를 사용하면 각 요청 후 컨텍스트가 얼마나 찼는지 차트로 보여 주는 창처럼 원하는 기능을 Claude Code에 추가할 수 있습니다. mod를 구성하는 파일과 전체 예시는 mod의 작동 방식을 참조하십시오.

[!NOTE]

Claude Code의 기존 훅도 이벤트가 발생할 때 실행되며, 설정 파일에서 구성한 셸 명령, HTTP 요청 또는 프롬프트 형태로 실행됩니다. 반면 mod의 핸들러는 Claude Code 내부에서 실행되는 함수입니다. Claude Code는 두 가지를 모두 훅이라고 부릅니다. 이 페이지들에서 "훅"은 mod의 핸들러를 의미하며, 설정 파일 방식의 훅은 "설정 훅"이라고 합니다.

mod로 할 수 있는 일

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

  • 직접 사용할 수 있는 인터페이스 그리기: 트랜스크립트 옆의 창이나 프롬프트 위의 띠 영역에 탭, 버튼, 텍스트 필드를 배치할 수 있습니다. 인터페이스에 그리기를 참조하세요.
  • Claude Code 자체 인터페이스 다시 그리기: 도구 호출 행, 스피너, Claude가 질문하는 대화 상자 등 Claude Code가 직접 그리는 부분을 교체하거나 스타일을 바꿀 수 있습니다. Claude Code가 이미 그리는 요소 변경하기를 참조하세요.
  • 도구 호출이나 요청에 개입하기: 예를 들어 사용자에게 질문하는 동안 도구 호출을 보류하거나, 도구를 실행하지 않고 응답하거나, 특정 요청을 다른 모델로 보낼 수 있습니다. 도구 호출 보호 또는 변경하기와 턴 추적하기를 참조하세요.
  • 명령으로 직접 작성한 코드 실행하기: Claude 턴 없이, Claude가 작업 중일 때도 함수를 즉시 실행하는 /command를 만들 수 있습니다. 명령 또는 도구 추가하기를 참조하세요.
  • 훅 간 데이터 공유하기: mod의 훅은 해당 파일의 변수를 공유하므로, 한 훅이 기록한 내용을 다른 훅이 표시할 수 있습니다. 예를 들어 한 훅이 도구 호출 수를 세고 다른 훅이 그 수를 스피너 옆에 표시하거나, 한 훅이 각 요청의 토큰 사용량을 읽고 다른 훅이 이를 창에 차트로 그릴 수 있습니다. 이벤트에 반응하기를 참조하세요.

mod는 Claude Code CLI, Claude Desktop 앱의 Code 탭, VS Code 확장 프로그램에서 작동합니다. claude -p, 클라우드 세션 등 다른 환경에서 mod가 어떻게 동작하는지는 mod가 실행되는 위치를 참조하세요. 설정 훅, 스킬 또는 MCP 서버로 이미 필요한 작업을 할 수 있다면 mod를 작성하기 전에 이들을 비교해 보세요. 조직의 mod를 관리하려면 조직의 mod 관리하기를 참조하세요.

mod 가져오기

mod를 시작하는 방법은 다음과 같습니다.

mod 설치 또는 업데이트

[!WARNING]

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를 실행하여 mod를 로드합니다. 그렇지 않으면 다음에 Claude Code를 시작할 때 로드됩니다.

샘플 mod 사용해 보기

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

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

샘플 mod는 사용자의 권한으로 실행됩니다. 로드하기 전에 mod가 하는 일을 확인하려면 해당 mod의 훅과 호출을 나열하세요.

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

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

mod를 신뢰할지 결정하기

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

mod가 접근할 수 있는 범위

mod는 사용자의 권한으로 실행되므로, 설치하기 전에 mod가 무엇에 접근할 수 있는지 알아 두어야 합니다. 로드된 mod는 다음을 수행할 수 있습니다.

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

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

관리형 설정이 있거나 Team 또는 Enterprise /login이 세션의 자격 증명인 경우, 기본적으로 mod의 승인은 사용자의 ask 규칙이나 PreToolUse 훅을 넘어 호출을 통과시키지 않습니다. 둘 다 없으면 mod는 ask 규칙이 확인을 요청할 호출이나 사용자의 PreToolUse 훅이 차단한 호출을 승인할 수 있습니다. mod가 deny 규칙이 거부하는 호출도 승인할 수 있는 경우를 확인하려면 훅으로 권한 확장하기를 참조하십시오.

mod는 Claude Code 인터페이스의 많은 부분을 다시 꾸밀 수 있지만, 권한 프롬프트는 변경할 수 없습니다. 프롬프트에 표시되는 내용은 mod가 바꿀 수 없습니다.

설치하기 전에 mod가 하는 작업 나열하기

mod를 설치하기 전에, mod를 실행하지 않고도 mod가 처리하는 이벤트와 Claude Code에 요청하는 작업(예: 파일 읽기 또는 네트워크 요청 수행)을 나열할 수 있습니다. 먼저 저장소를 클론하는 등의 방법으로 플러그인 파일을 가져옵니다. 그런 다음 셸에서 플러그인 디렉터리를 대상으로 claude plugin validate를 실행합니다.

claude plugin validate ./some-mod

출력의 hooks: 및 calls: 줄에는 mod가 처리하는 이벤트와 Claude Code에 요청하는 작업이 나열됩니다. mod가 할 수 있는 작업 검토하기에서 출력 예시와 주의 깊게 살펴봐야 할 호출을 확인할 수 있습니다.

mod 켜기 또는 끄기

mod는 기본적으로 켜져 있습니다. 터미널에서는 Claude Code v2.1.287 이상을 사용하십시오. Desktop 앱에는 자체 Claude Code가 포함되어 있으며, 여기서는 v2.1.286부터 mod가 작동합니다. mod를 사용하는 환경에서 버전을 확인하십시오.

  • 터미널: 셸에서 claude --version을 실행합니다. 이보다 오래된 버전이라면 Claude Code를 업데이트하십시오.
  • Desktop 앱: Code 탭의 로컬 세션에서 /status를 입력하고 Claude Code 행을 확인합니다. 이 행에는 2.1.286과 같은 버전이 표시됩니다. 이보다 오래된 버전이라면 Desktop 앱을 업데이트하십시오.

mod를 끄려면 몇 개의 mod를 중지할지, 그리고 얼마 동안 중지할지 선택합니다. 다시 켜려면 같은 변경을 되돌리면 됩니다.

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

조직을 통해 Claude Code를 사용하는 경우, 관리자가 로드되는 mod를 제한할 수도 있습니다. 관리자는 사용자가 설치한 mod의 로드 중지부터 시작하십시오.

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

사용자 환경에서 mod를 로드할 수 있는지 확인하려면 mod를 로드할 수 있는지 확인을 참조하십시오.

[!NOTE]

얼리 액세스 기간 중에 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS를 설정했다면 제거하십시오. Claude Code v2.1.287 이상에서는 이 값을 무시하므로, 0으로 설정해도 mod가 꺼진 상태로 유지되지 않습니다.

세션에서 로드한 mod 확인

터미널 세션에서 로드한 mod를 확인하려면 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… 순으로 표시됩니다.