메인 콘텐츠로 건너뛰기
mod가 처리할 수 있는 이벤트, 호출할 수 있는 mods API 메서드, 그릴 수 있는 렌더링 지점을 찾아볼 수 있습니다. 항목은 v2.1.290 기준 Claude Code CLI 및 Desktop 앱과 v2.1.299 기준 VS Code 확장 프로그램을 다룹니다. 각 항목에는 이름과 한 줄 설명이 있으며, 이를 설명하는 가이드 섹션이 있는 경우 해당 섹션으로 연결됩니다.
전체 참조는 Claude Code의 mod용 TypeScript 선언으로, 모든 이벤트, 메서드, 요소를 예제와 함께 설명합니다. GitHub의 사본은 설치된 Claude Code 버전보다 오래된 것일 수 있습니다. 두 내용이 서로 다를 경우 Claude Code가 해당 버전에 맞게 작성하는 사본을 신뢰하십시오.

파일

mod는 다음 파일로 구성된 플러그인 디렉터리입니다. register는 on과 options를 받습니다. options에는 매니페스트가 선언한 userConfig 필드의 값이 기본값이 채워진 상태로 담겨 있습니다.

훅 함수

mod는 register 안에서 on을 호출하여 이벤트 핸들러인 각 훅을 등록합니다. on은 이벤트 이름, 이벤트 필드에 대한 필터인 선택적 matcher, 그리고 훅을 인수로 받으며, 예를 들면 on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e))와 같습니다. on은 메서드 하나, 즉 .catch(handler)를 가진 등록 객체를 반환하며, 이 메서드는 훅의 오류 핸들러를 설정합니다.

이벤트

이벤트는 관련 대상별로 묶여 있으며, 각 이벤트마다 발생 시점과 해당 이벤트의 훅이 반환할 수 있는 값이 나와 있습니다. turn.step과 process.spawn의 훅은 비동기 제너레이터이고, 그 밖의 훅은 비동기 함수입니다. 각 표의 마지막 열은 약식 표기를 사용합니다. next(e)는 이벤트를 변경 없이 전달합니다. next({ ...e, text })는 next({ ...e, text: e.text.trim() })처럼 지정한 필드를 변경한 사본을 전달합니다. 객체를 반환하면 next를 호출하지 않고 이벤트에 응답하며, reason과 같은 단어는 { deny: 'Use the file tools.' }처럼 직접 작성하는 문자열을 나타냅니다.

도구

도구 이벤트는 Claude가 수행하는 각 도구 호출을 중심으로 발생하며, Claude가 읽는 설명부터 호출 실행 여부에 대한 결정까지 포함합니다.

tool.check의 에이전트 및 조직 필드

tool.check 훅에서 다음 필드를 읽어 서브에이전트의 호출과 메인 대화의 호출을 구분하고, 조직이 커넥터 도구에 대해 승인을 요구하는지 확인할 수 있습니다. tool.check에서 e.agentId와 e.ceiling을 사용하려면 Claude Code v2.1.290 이상이 필요합니다.

tool.check의 e.isReadOnly 필드

tool.check 훅에서 e.isReadOnly는 도구가 이 호출을 읽기 전용으로 보고할 때 true입니다. 그렇지 않으면 이 필드는 false가 아니라 아예 없습니다. 이 값은 도구 자체의 보고이므로, 이 필드만으로 호출을 승인하기 전에 도구 호출이 읽기 전용인지 확인하기를 먼저 읽어 보세요. tool.check에서 e.isReadOnly를 사용하려면 Claude Code v2.1.304 이상이 필요합니다.

프롬프트와 Claude가 읽는 내용

프롬프트 이벤트는 사용자가 입력하는 텍스트와, 시스템 프롬프트나 리마인더처럼 Claude Code가 자체적으로 Claude에 보내는 텍스트를 다룹니다.

skill.prompt의 소스 및 frontmatter 필드

skill.prompt 훅에서는 e.skill의 스킬 이름, e.text의 Claude가 읽는 텍스트와 함께 다음 필드를 읽을 수 있습니다. 훅은 변경한 text 또는 frontmatter를 next에 전달할 수 있습니다. 그 뒤의 훅은 둘 다 읽고, Claude는 최종 text를 읽습니다. 그 밖의 필드를 변경하는 훅은 실패합니다. skill.prompt에서 e.source, e.pluginName, e.path, e.frontmatter, e.frontmatterProblem을 사용하려면 Claude Code v2.1.299 이상이 필요합니다.

breakPromptCache로 변경한 시스템 프롬프트 섹션 또는 도구 설명 전송하기

실행 중인 대화에서 섹션이나 도구 설명을 변경하려면 $.ui.invalidate('prompt.section') 또는 $.ui.invalidate('tool.describe')를 호출하여 훅이 다시 실행되도록 합니다. 그리고 훅에서 { text, breakPromptCache: true } 또는 { description, breakPromptCache: true }를 반환합니다. 이 필드가 없으면 섹션이나 처음부터 로드된 도구에 대해 Claude는 새 대화가 시작되거나 압축이 이루어질 때까지 대화와 함께 저장된 텍스트를 계속 읽습니다. 변경한 텍스트는 다음 턴에 Claude에 전달되며 프롬프트 캐시가 처음부터 다시 시작되므로, 해당 턴은 더 느리고 비용이 더 많이 듭니다. 이 필드를 사용하려면 Claude Code v2.1.321 이상이 필요합니다. v2.1.299부터 v2.1.321 이전까지는 실행 중인 대화가 다음 턴에 변경된 텍스트를 받았습니다.

명령과 구성

settings.read의 e.layers 및 e.source

  • e.layers: 설정을 담고 있는 사용 중인 소스마다 하나씩 있는 { source, settings } 객체로, 우선순위가 가장 낮은 것부터 나열됩니다. settings.read 훅이 받는 값을 참조하세요.
  • e.source: $.settings.read({ source: 'policy' })처럼 mod가 요청한 하나의 소스입니다. Claude Code 자체의 읽기와 병합된 설정에 대한 읽기에서는 없습니다

턴

턴 이벤트는 하나의 답변을 시작부터 끝까지 추적하며, 그 안에서 모델로 보내는 각 요청도 포함합니다.

세션

세션 이벤트는 세션의 시작, 종료, 압축, 그리고 다른 세션과의 메시지 교환을 나타냅니다.

서브에이전트

서브에이전트 이벤트는 서브에이전트 유형이 Claude에 제공될 때와 서브에이전트 또는 에이전트 팀 팀원이 시작되기 직전에 발생합니다. agent.spawn 훅은 Claude가 SendMessage 도구로 메시지를 보낼 때처럼, 완료되었거나 중지된 서브에이전트가 다시 실행되기 직전에도 실행됩니다. 이 이벤트에서 e.resume은 { agentId }입니다. 훅이 서브에이전트 수를 센다면, 재개된 서브에이전트가 다시 집계되지 않도록 e.resume이 설정된 이벤트는 건너뛰세요. 재개된 실행을 거부하려면 { deny: reason }을 반환합니다. 실행은 시작되지 않으며, 서브에이전트는 기존 상태 그대로 유지됩니다. SendMessage 호출이 해당 실행을 요청한 경우, Claude는 그 호출의 결과로 a plugin declined the resume: 뒤에 지정한 이유가 붙은 텍스트를 읽습니다. 재개된 실행에 대해 다른 model처럼 변경한 이벤트를 next에 전달하면 Claude Code는 해당 변경을 무시합니다.
재개된 실행에 대한 이벤트를 사용하려면 Claude Code v2.1.299 이상이 필요합니다. v2.1.299 이전에는 서브에이전트가 재개될 때 agent.spawn 훅이 실행되지 않았습니다. 해당 버전에서 서브에이전트를 재개하는 SendMessage 호출을 거부하려면 tool.call 훅에서 해당 도구를 매칭하세요.

인터페이스

인터페이스 이벤트는 Claude Code가 렌더링 지점을 그릴 때와 사용자가 mod가 그린 컨트롤을 사용할 때 발생합니다. ui.render 훅이 반환하는 값은 인터페이스에 그리기에서 확인할 수 있습니다.

다른 mod

이 이벤트를 사용하면 mod가 다른 mod가 로드될 때 이에 작용하여, 로드를 거부하거나 해당 mod가 받는 mods API를 변경할 수 있습니다. engine.create에서 추가한 네임스페이스의 메서드를 다른 mod의 훅이 호출하면, 해당 이벤트의 모든 훅이 반환될 때까지 메서드의 $ 호출은 그 훅의 컨텍스트에서 실행됩니다. 예를 들어 상대 경로는 해당 훅의 작업 디렉터리를 기준으로 확인되며, $.prompt.submit은 턴이 해당 훅을 기다리는 동안 거부됩니다. 그 이후에 메서드가 수행하는 호출은 mod 자체의 컨텍스트에서 실행됩니다.

텔레메트리

텔레메트리 이벤트는 Claude Code가 로그에 기록하는 사용 기록에 대해 발생합니다.

설정 훅 이벤트

각 설정 훅 이벤트는 classic.Stop이나 classic.PostToolUse처럼 classic.<Event>라는 이름의 이벤트입니다. e는 훅의 stdin JSON입니다.

Mods API 호출

모든 mods API 메서드는 fs.read, model.complete, ui.open처럼 네임스페이스와 메서드 이름을 딴 이벤트이기도 합니다. 이러한 이벤트의 훅은 next(e), { deny: reason } 또는 { value }를 반환할 수 있습니다. 이 이벤트 중 일부는 Claude Code 자체의 동작에 대해서도 발생하므로, 이벤트를 거부하기 전에 next.origin.plugin이 engine인지 확인하세요.

Claude Code 자체 http.fetch 요청의 필드

http.fetch 훅에서 { plugin: 'engine', tier: 'core' }인 next.origin은 mod의 $.http.fetch 호출이 아니라 모델 요청과 같은 Claude Code 자체 요청임을 나타냅니다. 기본 제공 가드가 로드된 환경에서는 mod가 조직의 mod로 간주되는 경우를 제외하고 훅이 이러한 이벤트를 받지 않습니다. 이러한 이벤트에서 e.init과 next(e)가 확정하는 value에는 특히 다음 필드가 포함될 수 있습니다. 이러한 이벤트와 필드를 사용하려면 Claude Code v2.1.321 이상이 필요합니다.

Mods API 메서드

mods API는 모든 훅이 받는 $ 인수입니다. 이 API의 메서드는 $.ui와 같은 네임스페이스로 그룹화되어 있습니다. 이 표는 각 네임스페이스의 메서드를 이름별로 나열하므로, $.ui 행의 open은 $.ui.open(...) 호출을 의미합니다. 가이드에서는 자주 쓰이는 메서드의 사용 예를 보여 주며, 사용 중인 빌드의 타입에는 모든 메서드가 예제와 함께 문서화되어 있습니다.

렌더링 지점

렌더링 지점은 Claude Code 인터페이스의 확장 지점입니다. 각 행은 ui.render 훅에서 e.component의 값이며, e.props의 필드와 해당 지점을 렌더링하는 앱을 함께 보여 줍니다. e.surface는 terminal, desktop, vscode처럼 그리기를 수행하는 앱을 나타냅니다. Claude Code가 이미 그리는 요소 변경하기에서는 훅이 각 지점에서 무엇을 할 수 있는지를 선택지별 예시와 함께 보여 줍니다. VS Code 확장 프로그램에서 렌더링하려면 확장 프로그램 버전 2.1.299 이상이 필요합니다. 기능 플래그를 가져오지 않는 세션에서는 2.1.304 이상이 필요합니다. VS Code 확장 프로그램에서 그리기에 확장 프로그램이 다르게 그리는 요소가 정리되어 있습니다. e.viewport에는 columns, rows, isFullscreen이 들어 있습니다. 터미널과 Desktop 앱에서는 앱이 창 크기를 측정하기 전까지 존재하지 않습니다. 또한 이 경우 rows는 사용자의 창(pane)이 아니라 전체 윈도우의 높이입니다. VS Code 확장 프로그램에서는 항상 존재합니다. 트리를 해당 지점에 맞추려면 훅에서 다음 prop을 읽습니다.
  • Pane 또는 밴드의 너비: e.props.bodyColumns에 맞춰 그립니다
  • 트랜스크립트 옆에 있는 Pane의 높이: e.props.placement가 'dock'인 경우 e.props.scroll.bodyRows는 창이 트리에 제공하는 행 수입니다
  • 프롬프트 위에 있는 Pane의 높이: e.props.placement가 'inline'인 경우 창은 트리에 맞춰 한도까지 커지며, bodyRows가 그 한도입니다. $.ui.open의 rows 필드로 다른 한도를 요청할 수 있습니다.
창보다 높은 트리는 전체가 하나로 스크롤됩니다.

요소

요소는 ui.render 훅이 반환하는 트리의 구성 요소이며, $.ui.resolve(e)에서 가져옵니다. 요소로 트리 만들기에서는 자주 쓰이는 요소와 터미널이 이를 그리는 방식을 보여 주며, 인터페이스 갤러리에서는 대부분의 요소에 대한 스크린샷을 확인할 수 있습니다. 체크 표시는 앱이 해당 요소를 그릴 수 있음을 의미합니다. Button에 대한 추가 규칙:
  • action: Claude Code 자체의 키보드 단축키 액션 중 하나를 지정하며, 해당 액션에 대한 사용자의 바인딩이 코드(chord) 또는 수정자 키 조합인 경우 그 바인딩으로 버튼이 눌립니다
  • 밴드의 숫자 단축키: 밴드에 있는 버튼의 숫자 hotkey는 사용자가 빈 프롬프트에 해당 숫자만 입력하고 잠시 멈출 때도 실행됩니다
  • 접힌 밴드: 밴드가 접혀 있는 동안에는 action 바인딩과 단축키 모두 밴드 안의 버튼을 누르지 않습니다
  • 하나의 단축키를 지정한 두 버튼: 하나의 그리기에서 두 버튼이 동일한 hotkey를 지정하면 나중의 버튼이 이를 가져갑니다. 다른 mod의 버튼이 동일한 키를 사용하는 경우는 단축키가 작동하지 않음을 참조하십시오.
  • variant: primary 또는 secondary이며, 그 밖의 값은 오류를 발생시킵니다. 터미널에서 primary 버튼은 plain이 아닌 한 강조 색상으로 그려집니다.
  • role: dismiss는 닫기 버튼임을 표시하며, 그 밖의 값은 오류를 발생시킵니다. 닫기 동작은 onPress에서 직접 처리하십시오. 텍스트와 버튼 행을 포함하는 밴드에서 데스크톱 앱은 해당 행의 첫 번째 dismiss 버튼을 자체 닫기 컨트롤로 그릴 수 있습니다. 터미널은 role이 없을 때와 동일하게 버튼을 그립니다.
Button은 label 대신 children을 가질 수 있습니다.
  • children으로 사용할 수 있는 것: 이름 뒤에 흐린 세부 정보가 오거나 색상 칩이 붙는 경우처럼 문자열과 Text 요소를 사용할 수 있습니다. Claude Code는 Button 안의 그 밖의 요소를 거부합니다.
  • 버튼 이름 지정: label이 버튼의 이름을 지정하며, 기본값은 children의 텍스트입니다. 단일 문자열이 아닌 children을 가진 버튼에는 key 또는 label을 지정하십시오.
  • 터미널에서: children은 레이블이 표시될 자리에 그려지며, children의 어느 곳을 눌러도 한 번의 누름으로 처리되므로 목록의 각 행을 하나의 버튼으로 만들 수 있습니다
  • 데스크톱 앱과 VS Code 확장에서: 버튼은 label을 그립니다
단일 문자열이 아닌 children을 가진 Button을 사용하려면 Claude Code v2.1.295 이상이 필요합니다.
autoFocus는 모든 컨트롤에서 true만 허용하므로, 이를 끄려면 해당 prop을 생략하십시오. VS Code 확장은 일부 요소 prop을 무시하고, 해당 prop을 생략한 것처럼 요소를 그립니다.
  • Box: position과 그에 따른 top, left, right, bottom, 그리고 alignSelf, borderDimColor, hover
  • Text: size, mono, tabular, hover
  • Button: hotkey, plain, autoFocus, action, hover. 따라서 VS Code에서는 버튼을 클릭하거나, 버튼에 포커스가 있을 때 Enter를 눌러 버튼을 누릅니다. 확장은 variant와 role도 무시합니다.
  • Code: language, path, startLine, format, wrap. 따라서 코드는 색상이나 줄 번호 없이 그려지며, format: 'diff' 블록은 diff의 원시 텍스트를 표시합니다
  • Input 및 Select: autoFocus, 그리고 Input의 rows
  • Svg: isInteractive

Box 테두리 스타일

Box 주위에 테두리를 그리려면 borderStyle: 'round'처럼 borderStyle을 다음 이름 중 하나로 설정하십시오. 각 행은 해당 이름에 대해 터미널이 그리는 내용을 설명하고 테두리의 위쪽 가장자리를 보여 줍니다. borderStyle에 'rounded'처럼 그 밖의 이름을 지정한 Box는 테두리 없이 그려집니다.

Box 간격 단계

Box 간격 prop은 gap, columnGap, rowGap, padding, margin, 그리고 paddingX, marginTop처럼 padding과 margin의 한쪽 면 및 한 축 형태입니다. 각 prop은 gap: 1처럼 터미널 셀 수를 받거나, gap: 'md'처럼 단계 이름을 받습니다. 터미널과 VS Code 확장에서 각 단계는 다음 셀 수에 해당합니다. gap, padding 또는 margin을 단계로 설정하면 해당 단계가 가로와 세로에 동시에 적용됩니다. 예를 들어 터미널과 VS Code 확장에서 padding: 'md'는 양옆 각각 두 셀, 위아래 각각 한 행입니다. 단계 이름을 사용하려면 Claude Code v2.1.299 이상이 필요합니다. 이전 릴리스에서는 단계 이름을 사용하는 트리가 그려지지 않습니다.

Text 타이포그래피 prop

Text에 size, weight, mono 또는 tabular를 설정하면 트리를 그리는 앱에 텍스트 크기, 굵기, 고정폭 서체 또는 너비가 동일한 숫자를 요청할 수 있습니다. prop에 의존하기 전에 터미널과 VS Code 확장이 해당 prop을 어떻게 처리하는지 확인하십시오. 앱이 설정한 prop을 무시하더라도 트리는 여전히 그려지며, 텍스트는 해당 prop을 생략한 것처럼 표시됩니다. 이 네 가지 prop을 사용하려면 Claude Code v2.1.299 이상이 필요합니다. 이전 릴리스에서는 size, weight, mono 또는 tabular를 설정한 트리가 그려지지 않습니다.

bold를 weight로 대체하기

Text의 bold는 weight로 대체되어 deprecated되었지만 여전히 작동합니다. weight가 없는 Text에서 이를 대체하려면 bold: true를 weight: 'semibold'로 변경하십시오. Claude Code v2.1.299 이상에서 동일한 결과를 얻을 수 있습니다. v2.1.299 이전 릴리스에서는 weight를 설정한 트리가 그려지지 않습니다. Text에 bold와 weight를 모두 설정하면 bold는 효과가 없습니다.

제한

훅 및 mod API 호출은 시간 및 크기 제한 내에서 실행됩니다. Claude Code는 시간 제한을 초과한 훅을 건너뜁니다. 중첩, 요소, Raster 셀 또는 Image 바이트 제한을 초과한 트리는 그려지지 않습니다.

설정 및 환경 변수

다음은 mod에 영향을 주는 설정 및 환경 변수입니다. 위치 열은 각 항목을 어느 설정 파일 또는 환경에서 읽는지 나타냅니다. sec-default@builtin은 Claude Code에 기본 제공되는 가드로, /plugin 및 디버그 로그에는 cc-plugin-sec-default로 표시됩니다. 이 가드가 로드되는 경우, 사용자가 설치하는 모든 mod보다 먼저 실행됩니다. 관리형 prependPlugins가 설정된 경우, 이 가드는 해당 목록에 이름이 포함된 경우에만 나열된 위치에서 로드됩니다. 소스는 Claude Code 저장소의 mods/sec-default 디렉터리에 있습니다.

명령

다음 명령과 플래그는 mod를 로드하고, 검사하고, 테스트합니다. claude 명령은 셸에서 실행하고 / 명령은 Claude Code 프롬프트에서 실행합니다. 표에서 <directory>는 claude plugin validate ./first-mod처럼 직접 입력하는 경로를 나타냅니다. 대괄호는 선택적 인수를 표시합니다.