Mods 참조
Claude Code mod에 대한 전체 참조: 훅 모듈 레이아웃, 이벤트, mods API 메서드, 렌더링 지점, 사용 환경별 요소, 제한 및 설정.
mod가 처리할 수 있는 이벤트, 호출할 수 있는 mods API 메서드, 그릴 수 있는 렌더링 지점을 찾아볼 수 있습니다. 항목은 v2.1.290 기준 Claude Code CLI 및 Desktop 앱과 v2.1.299 기준 VS Code 확장 프로그램을 다룹니다. 각 항목에는 이름과 한 줄 설명이 있으며, 이를 설명하는 가이드 섹션이 있는 경우 해당 섹션으로 연결됩니다.
[!NOTE]
전체 참조는 Claude Code의 mod용 TypeScript 선언으로, 모든 이벤트, 메서드, 요소를 예제와 함께 설명합니다. GitHub의 사본은 설치된 Claude Code 버전보다 오래된 것일 수 있습니다. 두 내용이 서로 다를 경우 Claude Code가 해당 버전에 맞게 작성하는 사본을 신뢰하십시오.
파일
mod는 다음 파일로 구성된 플러그인 디렉터리입니다.
| 파일 | 필수 여부 | 내용 |
|---|---|---|
.claude-plugin/plugin.json |
예 | 플러그인 매니페스트입니다. mod는 필수 필드를 추가하지 않습니다. |
hooks/hooks.json |
예 | modules: "modules": ["./register.js"]처럼 훅 모듈에 대한 경로 하나를 이 파일 기준 상대 경로로 담은 배열입니다. hooks 아래에 설정 훅을 포함할 수도 있습니다. |
hooks/register.js와 같은 훅 모듈 |
예 | mod의 진입점입니다. register(on, options)를 내보냅니다. 파일 이름은 .js, .mjs, .cjs, .jsx, .ts, .mts, .cts 또는 .tsx로 끝납니다. ES 모듈입니다. |
types/index.d.ts(매니페스트의 types가 다른 경로를 지정하지 않는 경우) |
mod가 $.state를 사용하거나 mods API에 네임스페이스를 추가하는 경우 |
PluginState 값과 mod가 추가하는 모든 네임스페이스를 선언합니다. 매니페스트에서 types를 생략하려면 v2.1.299 이상이 필요합니다. |
이름이 .test.ts 또는 .test.tsx로 끝나는 파일 |
아니요 | claude plugin test가 실행하는 테스트입니다 |
register는 on과 options를 받습니다. options에는 매니페스트가 선언한 userConfig 필드의 값이 기본값이 채워진 상태로 담겨 있습니다.
훅 함수
mod는 register 안에서 on을 호출하여 이벤트 핸들러인 각 훅을 등록합니다. on은 이벤트 이름, 이벤트 필드에 대한 필터인 선택적 matcher, 그리고 훅을 인수로 받으며, 예를 들면 on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e))와 같습니다. on은 메서드 하나, 즉 .catch(handler)를 가진 등록 객체를 반환하며, 이 메서드는 훅의 오류 핸들러를 설정합니다.
| 인수 | 설명 |
|---|---|
$ |
mods API: mods API 메서드에 있는 모든 메서드입니다. 각 호출은 $.fs.read('notes.md')처럼 네임스페이스 다음에 메서드를 붙여 전체 형태로 작성합니다. |
e |
깊게 동결된 일반 데이터 형태의 이벤트 입력입니다. 이를 변경하려면 복사본을 next에 전달합니다. |
next(e) |
미들웨어에서와 같은 다음 핸들러입니다. 이 훅 이후의 훅들을 실행한 다음 Claude Code의 동작을 실행합니다. 이벤트의 결과로 resolve됩니다. |
next.signal |
이벤트가 중단되면 abort되는 AbortSignal입니다 |
next.origin |
이벤트를 발생시킨 주체의 { plugin, tier }입니다. Claude Code 자체는 { plugin: 'engine', tier: 'core' }입니다. mod의 tier는 mod 실행 순서에서의 우선순위 그룹으로, prepend, user, append, builtin 중 하나입니다. |
next.budget |
밀리초 단위의 훅 시간 제한입니다. next.budget.ms는 전체 제한이고, next.budget.remainingMs는 현재 남은 시간입니다 |
next.to(e, tier) |
이후의 tier인 append, builtin, core 중 하나로 건너뜁니다. next.to(e, 'append')는 사용자가 설치한 mod를 건너뜁니다. prependPlugins 또는 appendPlugins에 있는 mod만 이를 호출할 수 있습니다. |
next.error |
.catch 핸들러에서만 사용할 수 있습니다. 훅이 실패한 경우 kind는 throw 또는 timeout이고, message는 오류의 텍스트입니다. 이벤트가 해당 훅의 mods API 호출 내부 또는 훅 외부에 있는 mod 코드의 mods API 호출 내부에서 발생하여 훅을 건너뛴 경우 kind는 re-entry입니다. re-entry는 Claude Code v2.1.292 이상이 필요합니다. |
next.error.cause |
kind가 re-entry인 경우에만 설정됩니다. tool.call 또는 PreToolUse 훅이 이벤트가 발생한 mods API 호출을 변경했거나, agent.spawn 훅이 해당 호출로 시작된 에이전트를 변경한 경우 rewritten입니다. 다른 mod가 mods API에 추가한 메서드가 해당 이벤트를 발생시킨 경우, rewritten에도 해당하지 않는 한 lent입니다. lent는 Claude Code v2.1.292 이상, rewritten은 v2.1.300 이상이 필요합니다. |
next.called |
.catch 핸들러에서만 사용할 수 있습니다. 훅이 next를 호출한 경우 true입니다. |
이벤트
이벤트는 관련 대상별로 묶여 있으며, 각 이벤트마다 발생 시점과 해당 이벤트의 훅이 반환할 수 있는 값이 나와 있습니다. 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.call |
도구가 실행되기 직전 | next(e), { deny: reason } 또는 { result } |
tool.check |
tool.call 및 PreToolUse 훅 이후, Claude Code가 도구 호출의 실행 허용 여부를 결정할 때. next(e)는 규칙, 권한 모드, 그리고 해당 훅들이 내린 결정으로 확정됩니다. |
next(e) 또는 { decision }. decision은 allow, ask 또는 deny로 설정하며, 선택적으로 reason을 함께 지정할 수 있습니다 |
tool.describe |
각 도구의 설명이 Claude에 처음 전송될 때 도구마다 한 번. MCP 도구의 경우 Claude가 도구 검색을 통해 해당 도구를 로드할 때 한 번 더 발생하며, 이때 e.description은 로드된 도구에 대해 Claude가 읽는 텍스트로 설정됩니다. |
{ description }. 선택적으로 isDeferred를 함께 지정할 수 있으며, true로 설정하면 도구를 도구 검색 뒤에 두고 false로 설정하면 처음부터 로드합니다 |
tool.check의 에이전트 및 조직 필드
tool.check 훅에서 다음 필드를 읽어 서브에이전트의 호출과 메인 대화의 호출을 구분하고, 조직이 커넥터 도구에 대해 승인을 요구하는지 확인할 수 있습니다.
e.agentId: 서브에이전트 또는 인프로세스 팀원이 호출할 때 설정되며, 메인 대화가 호출할 때는 없습니다e.ceiling: 해당 설정이 Claude Code에 도달하는 세션에서, 조직이ask로 설정한 커넥터 도구의 경우ask입니다
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에 보내는 텍스트를 다룹니다.
| 이벤트 | 발생 시점 | 훅이 반환할 수 있는 값 |
|---|---|---|
prompt.submit |
프롬프트가 제출될 때 | next({ ...e, text }), next({ ...e, context }) 또는 { drop: reason } |
prompt.fill, prompt.suggest |
텍스트가 초안으로, 또는 흐린 제안으로 프롬프트 입력란에 들어가기 직전 | 텍스트를 변경한 next(e) |
prompt.edit |
사용자가 프롬프트 입력란을 편집할 때 | next(e) |
prompt.autocomplete |
사용자가 프롬프트 입력란에 입력하고 커서 위치에서 단어가 끝날 때. e.token은 해당 단어입니다. Claude Code는 훅을 기다리지 않으며, 자체 자동 완성 행이 먼저 표시됩니다. |
{ suggestions }(Claude Code 자체 행 아래에 표시되는 { text, label, description } 행 목록). 행을 선택하면 해당 행의 text가 단어를 대체합니다. |
prompt.compose |
Claude Code가 시스템 프롬프트를 렌더링할 때 | { sections }(전송 순서대로 나열한 { id, text, scope } 목록) |
prompt.section |
시스템 프롬프트의 이름 있는 섹션마다 한 번. e.name은 prompt.compose에서의 섹션 id입니다. |
{ text }, 또는 섹션을 생략하려면 { text: null } |
prompt.context |
대화마다 한 번, 첫 메시지와 함께 전송되는 컨텍스트에 대해 | { blocks } |
prompt.attachment |
Claude Code가 리마인더처럼 Claude를 위한 자체 메시지를 추가할 때. e.type은 종류를 나타내며, 타입에 선언된 종류의 경우 e.detail에 텍스트 작성의 근거가 된 정보가 담깁니다. |
{ text }, 또는 생략하려면 { text: null } |
prompt.mention |
Claude Code가 프롬프트에서 @-멘션한 파일을 읽기 직전. Claude Code v2.1.290 이상이 필요합니다. | 다른 파일을 읽으려면 next({ ...e, path }), 또는 { deny: reason } |
skill.prompt |
스킬의 텍스트가 Claude용으로 확장될 때 | { text } |
attribution.text |
Claude Code가 커밋 또는 풀 리퀘스트의 저작자 표시 텍스트를 작성할 때 | { text } |
skill.prompt의 소스 및 frontmatter 필드
skill.prompt 훅에서는 e.skill의 스킬 이름, e.text의 Claude가 읽는 텍스트와 함께 다음 필드를 읽을 수 있습니다.
| 필드 | 타입 | 담긴 내용 |
|---|---|---|
e.source |
string | 스킬을 제공하는 주체: 엔터프라이즈, 개인, 프로젝트 위치의 스킬에 대해 각각 policySettings, userSettings, projectSettings입니다. 그 밖의 소스는 plugin, mcp, syncedSkills, built-in 같은 단어를 제공합니다. |
e.pluginName |
string | e.source가 plugin인 스킬의 경우 플러그인 이름 |
e.path |
string | 스킬의 SKILL.md 파일의 절대 경로, 또는 명령 파일로 작성된 스킬의 경우 해당 .md 파일의 절대 경로. 기본 제공 스킬처럼 이 머신에 파일이 없는 스킬의 경우에는 없습니다. |
e.frontmatter |
object | 일반 데이터 형태로 된 스킬 파일의 frontmatter |
e.frontmatterProblem |
string | e.frontmatter에 파일의 frontmatter 또는 그 키 중 하나가 빠져 있는 이유(예: is a list or a single value, not a table). e.frontmatter에 frontmatter 전체가 담겨 있거나 스킬에 frontmatter가 없으면 없습니다. |
훅은 변경한 text 또는 frontmatter를 next에 전달할 수 있습니다. 그 뒤의 훅은 둘 다 읽고, Claude는 최종 text를 읽습니다. 그 밖의 필드를 변경하는 훅은 실패합니다.
skill.prompt에서 e.source, e.pluginName, e.path, e.frontmatter, e.frontmatterProblem을 사용하려면 Claude Code v2.1.299 이상이 필요합니다.
명령과 구성
| 이벤트 | 발생 시점 | 훅이 반환할 수 있는 값 |
|---|---|---|
command.run |
명령이 실행되기 직전 | { text }, {} 또는 next(e) |
command.describe |
명령 목록을 위해 명령마다 한 번 | { description, argumentHint, isHidden } |
config.set |
/config 행이 변경되기 직전 |
next({ ...e, value }) 또는 { deny: reason } |
config.describe |
/config 행마다 한 번 |
{ label, description, isHidden } |
settings.read |
mod가 $.settings.read를 호출하거나, Claude Code가 세션의 병합된 설정을 만들 때. Claude Code 자체의 읽기 시 발생과 e.layers에는 Claude Code v2.1.304 이상이 필요합니다 |
next(e), { value } 또는 { deny: reason } |
settings.read의 e.layers 및 e.source
e.layers: 설정을 담고 있는 사용 중인 소스마다 하나씩 있는{ source, settings }객체로, 우선순위가 가장 낮은 것부터 나열됩니다.settings.read훅이 받는 값을 참조하세요.e.source:$.settings.read({ source: 'policy' })처럼 mod가 요청한 하나의 소스입니다. Claude Code 자체의 읽기와 병합된 설정에 대한 읽기에서는 없습니다
턴
턴 이벤트는 하나의 답변을 시작부터 끝까지 추적하며, 그 안에서 모델로 보내는 각 요청도 포함합니다.
| 이벤트 | 발생 시점 | 훅이 반환할 수 있는 값 |
|---|---|---|
turn.start |
턴이 시작될 때 | next(e) |
turn.step |
하나의 요청이 모델로 전송되기 직전 | yield* next(e), 또는 next({ ...e, model }), next({ ...e, effort }) |
turn.complete |
턴이 종료되었을 때 | next(e), 또는 답변 아래에 한 줄을 표시하려면 { text } |
세션
세션 이벤트는 세션의 시작, 종료, 압축, 그리고 다른 세션과의 메시지 교환을 나타냅니다.
| 이벤트 | 발생 시점 | 훅이 반환할 수 있는 값 |
|---|---|---|
session.start |
로드된 mod마다 첫 프롬프트 전에 한 번, 그리고 해당 mod를 다시 로드한 후에 다시 한 번. /clear, /resume 또는 /branch 이후에는 발생하지 않습니다. |
next(e) |
session.end |
세션이 종료되거나 /clear, /resume 또는 /branch가 실행될 때. e.reason은 clear, resume, logout, prompt_input_exit 또는 other입니다. /branch는 resume으로 보고됩니다. |
next(e) |
session.compact |
대화가 압축되기 직전 | { skip: reason } |
session.receive, session.send |
다른 에이전트나 세션에서 메시지가 도착하거나, 다른 에이전트나 세션으로 메시지가 전송되기 직전. 세션 간 메시지 주고받기를 참조하세요. | receive의 경우 { consumed: reason }, send의 경우 { isDelivered: false, reason } |
session.append |
프롬프트, 응답 블록, 도구 결과, 알림 등 대화가 보관하는 각 행이 저장되기 전에 행마다 한 번 | 행의 텍스트 블록이나 그 안에 있는 tool_result 블록의 content를 다시 작성하려면 message.content를 변경한 next({ ...e, message }) |
session.attach, session.detach |
다른 앱이 세션에 연결되거나 연결이 끊길 때 | next(e) |
session.measure |
각 턴이 끝난 후, 그리고 플랜 한도의 사용 비율이 변경될 때 | next(e) |
서브에이전트
서브에이전트 이벤트는 서브에이전트 유형이 Claude에 제공될 때와 서브에이전트 또는 에이전트 팀 팀원이 시작되기 직전에 발생합니다.
| 이벤트 | 발생 시점 | 훅이 반환할 수 있는 값 |
|---|---|---|
agent.offer |
서브에이전트 유형이 Claude에 제공될 때 | 제공하지 않으려면 { isOffered: false } |
agent.spawn |
서브에이전트 또는 에이전트 팀 팀원이 시작되기 직전, 또는 완료되었거나 중지된 서브에이전트가 다시 실행되기 직전. 팀원의 경우 e.isTeammate는 true입니다. 재개된 실행의 경우 e.resume이 설정됩니다. |
시작되는 서브에이전트나 팀원의 모델을 선택하려면 next({ ...e, model }), 또는 { deny: reason } |
agent.spawn 훅은 Claude가 SendMessage 도구로 메시지를 보낼 때처럼, 완료되었거나 중지된 서브에이전트가 다시 실행되기 직전에도 실행됩니다. 이 이벤트에서 e.resume은 { agentId }입니다. 훅이 서브에이전트 수를 센다면, 재개된 서브에이전트가 다시 집계되지 않도록 e.resume이 설정된 이벤트는 건너뛰세요.
재개된 실행을 거부하려면 { deny: reason }을 반환합니다. 실행은 시작되지 않으며, 서브에이전트는 기존 상태 그대로 유지됩니다. SendMessage 호출이 해당 실행을 요청한 경우, Claude는 그 호출의 결과로 a plugin declined the resume: 뒤에 지정한 이유가 붙은 텍스트를 읽습니다. 재개된 실행에 대해 다른 model처럼 변경한 이벤트를 next에 전달하면 Claude Code는 해당 변경을 무시합니다.
[!NOTE]
재개된 실행에 대한 이벤트를 사용하려면 Claude Code v2.1.299 이상이 필요합니다. v2.1.299 이전에는 서브에이전트가 재개될 때
agent.spawn훅이 실행되지 않았습니다. 해당 버전에서 서브에이전트를 재개하는SendMessage호출을 거부하려면tool.call훅에서 해당 도구를 매칭하세요.
인터페이스
인터페이스 이벤트는 Claude Code가 렌더링 지점을 그릴 때와 사용자가 mod가 그린 컨트롤을 사용할 때 발생합니다. ui.render 훅이 반환하는 값은 인터페이스에 그리기에서 확인할 수 있습니다.
| 이벤트 | 발생 시점 |
|---|---|
ui.render |
렌더링 지점이 그려지기 직전 |
ui.resolve |
mod가 로드될 때, 앱, 렌더링 지점, mod 조합마다 한 번. 결과는 $.ui.resolve(e)가 읽는 요소 테이블입니다. |
ui.press, ui.input, ui.select |
mod가 그린 Button, Input 또는 Select가 사용될 때 |
ui.focus, ui.scroll |
포커스된 컨트롤, 또는 창이나 밴드의 스크롤 위치가 변경되기 직전 |
ui.close |
창이 닫히기 직전. e.id는 해당 창이며 e.origin.kind는 plugin, person 또는 unload입니다. |
ui.message |
Client 요소가 자신의 mod에 데이터를 게시할 때 |
ui.fault |
mod가 그린 Client 요소가 로드, 그리기 또는 실행에 실패했을 때. e.phase는 load, render 또는 run이며, e.reason은 오류 메시지입니다. Claude Code v2.1.289 이상이 필요합니다. |
다른 mod
이 이벤트를 사용하면 mod가 다른 mod가 로드될 때 이에 작용하여, 로드를 거부하거나 해당 mod가 받는 mods API를 변경할 수 있습니다.
| 이벤트 | 발생 시점 | 훅이 반환할 수 있는 값 |
|---|---|---|
plugin.register |
훅 모듈이 로드되기 직전. e.uses는 해당 모듈의 이벤트, mods API 호출, 환경 변수, 상태를 claude plugin validate가 출력하는 형식으로 나열합니다. 각 호출은 fs.read처럼 $. 접두사 없이 작성됩니다. |
{ refuse: reason } |
engine.create |
이 mod를 위한 mods API가 구성될 때 | 네임스페이스를 추가하도록 변경한 mods API. user 계층 외부의 mod는 네임스페이스를 제외할 수도 있습니다. |
engine.create에서 추가한 네임스페이스의 메서드를 다른 mod의 훅이 호출하면, 해당 이벤트의 모든 훅이 반환될 때까지 메서드의 $ 호출은 그 훅의 컨텍스트에서 실행됩니다. 예를 들어 상대 경로는 해당 훅의 작업 디렉터리를 기준으로 확인되며, $.prompt.submit은 턴이 해당 훅을 기다리는 동안 거부됩니다. 그 이후에 메서드가 수행하는 호출은 mod 자체의 컨텍스트에서 실행됩니다.
텔레메트리
텔레메트리 이벤트는 Claude Code가 로그에 기록하는 사용 기록에 대해 발생합니다.
| 이벤트 | 발생 시점 | 훅이 반환할 수 있는 값 |
|---|---|---|
telemetry.log, telemetry.mark |
텔레메트리 기록이 로그에 기록되기 직전, 또는 기능 사용 1회가 표시될 때. 설치하는 mod에서는 on('telemetry.log', { to: 'collector' }, hook)처럼 텔레메트리 훅에 { to: 'collector' } 필터를 지정해야 합니다. 필터가 없으면 해당 mod는 claude plugin validate를 통과하지 못합니다. *는 이 이벤트와 일치하지 않습니다. |
next(e) 또는 { deny: reason } |
설정 훅 이벤트
각 설정 훅 이벤트는 classic.Stop이나 classic.PostToolUse처럼 classic.<Event>라는 이름의 이벤트입니다. e는 훅의 stdin JSON입니다.
Mods API 호출
모든 mods API 메서드는 fs.read, model.complete, ui.open처럼 네임스페이스와 메서드 이름을 딴 이벤트이기도 합니다. 이러한 이벤트의 훅은 그 뒤에 실행되는 mod의 호출을 가로채며, next(e), { deny: reason } 또는 { value }를 반환할 수 있습니다.
Mods API 메서드
mods API는 모든 훅이 받는 $ 인수입니다. 이 API의 메서드는 $.ui와 같은 네임스페이스로 그룹화되어 있습니다. 이 표는 각 네임스페이스의 메서드를 이름별로 나열하므로, $.ui 행의 open은 $.ui.open(...) 호출을 의미합니다. 가이드에서는 자주 쓰이는 메서드의 사용 예를 보여 주며, 사용 중인 빌드의 타입에는 모든 메서드가 예제와 함께 문서화되어 있습니다.
| 네임스페이스 | 메서드 |
|---|---|
$.plugin |
name, root: 이 플러그인의 이름과 디렉터리 |
$.ui |
resolve, invalidate, open, close, panes, focus, scroll, toast, notify, status, log, notice, ask, copy, selection, blit |
$.command |
register, run, list |
$.tool |
register, call, check, list |
$.agent |
register, spawn, list. list()는 이 세션의 서브에이전트와 팀원을 반환하며, 각 항목의 status는 pending, running, waiting, idle, completed, failed, killed 중 하나입니다. 이 중 idle과 waiting에는 Claude Code v2.1.289 이상이 필요합니다. |
$.model |
complete, fork, classify |
$.prompt |
submit, read, fill, suggest, compose. Claude는 해당 mod를 발신자로 명시하는 문장 뒤에 오는 submit({ text })의 텍스트를 읽습니다. submit({ text, asUser: true })는 그 문장 없이 텍스트를 사용자 본인의 말로 보냅니다. |
$.turn |
abort |
$.session |
messages, cwd, root, model, turns, id, repo, surfaces, usage, version, compact, send, append, authorize. usage()는 { startedAt, context, rateLimits, cost }를 반환합니다. context에는 tokens, window, percent가 있으며, rateLimits는 { kind, percentUsed, resetsAt }의 목록입니다. |
$.config |
list, set |
$.settings |
read |
$.env |
get, set |
$.fs |
read, write, list, exists, stat, ancestors. write는 원자적이지 않습니다. 파일의 내용을 제자리에서 교체하므로 다른 프로세스가 일부만 기록된 파일을 읽을 수 있습니다. 여러 세션이 변경하는 데이터는 $.store에 보관하십시오. |
$.store |
get, set, delete, keys. 머신의 모든 세션이 공유하는 키-값 저장소입니다. 둘 이상의 세션에서 저장하기를 참조하십시오. |
$.state |
반응형 상태: get, set, 그리고 claude-code에서 가져오는 헬퍼 atom, read, update, derive, memberOf |
$.clock |
now, sleep, after, every |
$.http |
fetch |
$.process |
run, spawn |
$.mcp |
call, connect. connect(server)는 해당 플러그인의 매니페스트에 나열된 MCP 서버에 연결합니다. |
$.audio |
play, speak |
$.telemetry |
log, mark. 레코드는 Claude Code 또는 내장 mod가 호출한 경우에만 전송됩니다. |
렌더링 지점
렌더링 지점은 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.props |
e.requestId |
렌더링 위치 |
|---|---|---|---|
Pane |
title, isFocused, bodyColumns, placement, scroll, view |
창의 id |
터미널, Desktop, VS Code |
AbovePrompt |
hasSurvey, isWorking, maxRows, bodyColumns, scroll, view |
단일 인스턴스 | 터미널, Desktop |
UserMessage |
text, origin, isExpanded, 그리고 origin에 따라 task 또는 from |
메시지 id | 터미널, Desktop, VS Code |
AssistantMessage |
응답의 텍스트 | 메시지 id | 터미널, Desktop, VS Code |
ToolUse, ToolResult, ToolGroup |
도구의 이름, 입력, 결과 | 도구 호출 id | 터미널, Desktop, VS Code |
CommandOutput |
command, text |
메시지 id | 터미널, Desktop |
AskUserQuestion |
질문과 선택지 | 도구 호출 id | 터미널, Desktop, VS Code |
ToolProgress |
kind |
도구 호출 id | 터미널 |
Spinner |
word, message, suffix, mode |
에이전트 id | 터미널, Desktop, VS Code |
TurnDuration |
word, durationMs |
메시지 id | 터미널 |
InfoNotice |
text, command |
메시지 id | 터미널 |
SessionMode |
modes |
단일 인스턴스 | 터미널, Desktop |
PromptHint |
isDraft, isWorking, hint |
단일 인스턴스 | 터미널, Desktop |
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)에서 가져옵니다. 요소로 트리 만들기에서는 자주 쓰이는 요소와 터미널이 이를 그리는 방식을 보여 주며, 인터페이스 갤러리에서는 대부분의 요소에 대한 스크린샷을 확인할 수 있습니다. 체크 표시는 앱이 해당 요소를 그릴 수 있음을 의미합니다.
| 요소 | 주요 prop | 터미널 | 데스크톱 | VS Code |
|---|---|---|---|---|
Box |
key, flex 레이아웃, gap, padding, margin, width, height, minWidth, minHeight, borderStyle, borderColor, borderDimColor, backgroundColor, position, top, left, right, bottom, overflow, display, hover |
✓ | ✓ | ✓ |
Text |
color, backgroundColor, bold, italic, underline, strikethrough, dimColor, inverse, wrap, size, weight, mono, tabular, hover |
✓ | ✓ | ✓ |
Button |
key, label, children, onPress, hotkey, plain, dimColor, autoFocus, action, variant, role, hover |
✓ | ✓ | ✓ |
Link |
href, label. 제한 사항을 참조하십시오. |
✓ | ✓ | ✓ |
Code |
source, language, path, startLine, format, wrap |
✓ | ✓ | ✓ |
Markdown |
text, key, dimColor, onLinkPress, pressableLinks |
✓ | ✓ | ✓ |
Input |
key, label, placeholder, value, submitLabel, rows, onSubmit, onInput, autoFocus |
✓ | ✓ | ✓ |
Select |
key, label, options, value, onSelect, autoFocus |
✓ | ✓ | ✓ |
Svg |
최대 131,072자의 SVG 마크업으로 된 source, alt 텍스트, width, height, isInteractive |
✓ | ✓ | |
Client |
module, key, props, width, height, flexGrow |
✓ | ✓ | |
Raster |
key, 최대 512의 columns, 최대 256의 rows, cells. 색상 셀 그리드 그리기를 참조하십시오. |
✓ | ||
Image |
key, 최대 2 MiB의 PNG 또는 RGBA 바이트나 파일 경로 같은 source, 각각 최대 255의 columns 및 rows, alt 텍스트. 이를 그리는 터미널을 참조하십시오. |
✓ |
Button에 대한 추가 규칙:
action: Claude Code 자체의 키보드 단축키 액션 중 하나를 지정하며, 해당 액션에 대한 사용자의 바인딩이 코드(chord) 또는 수정자 키 조합인 경우 그 바인딩으로 버튼이 눌립니다- 밴드의 숫자 단축키: 밴드에 있는 버튼의 숫자
hotkey는 사용자가 빈 프롬프트에 해당 숫자만 입력하고 잠시 멈출 때도 실행됩니다 - 접힌 밴드: 밴드가 접혀 있는 동안에는
action바인딩과 단축키 모두 밴드 안의 버튼을 누르지 않습니다 - 하나의 단축키를 지정한 두 버튼: 하나의 그리기에서 두 버튼이 동일한
hotkey를 지정하면 나중의 버튼이 이를 가져갑니다 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을 그립니다
[!NOTE]
단일 문자열이 아닌 children을 가진
Button을 사용하려면 Claude Code v2.1.295 이상이 필요합니다.
autoFocus는 모든 컨트롤에서 true만 허용하므로, 이를 끄려면 해당 prop을 생략하십시오.
VS Code 확장은 일부 요소 prop을 무시하고, 해당 prop을 생략한 것처럼 요소를 그립니다.
Box:position과 그에 따른top,left,right,bottom, 그리고alignSelf,borderDimColor,hoverText:size,mono,tabular,hoverButton:hotkey,plain,autoFocus,action,hover. 따라서 VS Code에서는 버튼을 클릭하거나, 버튼에 포커스가 있을 때 Enter를 눌러 버튼을 누릅니다. 확장은variant와role도 무시합니다.Code:language,path,startLine,format,wrap. 따라서 코드는 색상이나 줄 번호 없이 그려지며,format: 'diff'블록은 diff의 원시 텍스트를 표시합니다Input및Select:autoFocus, 그리고Input의rowsSvg:isInteractive
Box 테두리 스타일
Box 주위에 테두리를 그리려면 borderStyle: 'round'처럼 borderStyle을 다음 이름 중 하나로 설정하십시오. 각 행은 해당 이름에 대해 터미널이 그리는 내용을 설명하고 테두리의 위쪽 가장자리를 보여 줍니다.
borderStyle |
터미널이 그리는 내용 | 위쪽 가장자리 |
|---|---|---|
'single' |
모서리가 각진 가는 선 | ┌──┐ |
'double' |
이중선 | ╔══╗ |
'round' |
모서리가 둥근 가는 선 | ╭──╮ |
'bold' |
굵은 선 | ┏━━┓ |
'singleDouble' |
위아래는 가는 선, 양옆은 이중선 | ╓──╖ |
'doubleSingle' |
위아래는 이중선, 양옆은 가는 선 | ╒══╕ |
'classic' |
ASCII 문자 +, -, | |
+--+ |
'arrow' |
Box 안쪽을 가리키는 화살표 |
↘↓↓↙ |
'dashed' |
모서리가 비어 있는 점선 | ╌╌ |
'quote' |
왼쪽에 세로로 이어지는 막대 ▎와 나머지 세 면의 빈 셀 |
빈칸 |
borderStyle에 'rounded'처럼 그 밖의 이름을 지정한 Box는 테두리 없이 그려집니다.
Box 간격 단계
Box 간격 prop은 gap, columnGap, rowGap, padding, margin, 그리고 paddingX, marginTop처럼 padding과 margin의 한쪽 면 및 한 축 형태입니다. 각 prop은 gap: 1처럼 터미널 셀 수를 받거나, gap: 'md'처럼 단계 이름을 받습니다. 터미널과 VS Code 확장에서 각 단계는 다음 셀 수에 해당합니다.
| 단계 | 가로 셀 수 | 세로 셀 수 |
|---|---|---|
'xs' |
1 | 0 |
'sm' |
1 | 0 |
'md' |
2 | 1 |
'lg' |
3 | 1 |
'xl' |
4 | 2 |
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 | 값 | 터미널에서 | VS Code 확장에서 |
|---|---|---|---|
size |
'caption', 'footnote', 'body', 'heading' 또는 'title' |
무시됨: 터미널에는 텍스트 크기가 하나뿐입니다 | 무시됨 |
weight |
'regular', 'medium', 'semibold' 또는 'bold' |
semibold와 bold는 굵은 텍스트로 그려집니다 |
semibold와 bold는 굵은 텍스트로 그려집니다 |
mono |
앱의 고정폭 서체를 요청하려면 true |
무시됨: 터미널은 항상 고정폭입니다 | 무시되므로 텍스트는 확장 자체의 서체를 유지합니다 |
tabular |
제자리에서 업데이트되는 숫자나 숫자 열이 정렬된 상태를 유지하도록 너비가 동일한 숫자를 요청하려면 true |
무시됨: 터미널의 숫자는 이미 한 셀 너비입니다 | 무시됨 |
이 네 가지 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 바이트 제한을 초과한 트리는 그려지지 않습니다.
| 제한 | 값 |
|---|---|
하나의 이벤트에 대한 훅 자체의 실행 시간(next 내부 시간 또는 $.clock.sleep을 제외한 mod API 호출 시간은 포함하지 않음) |
10초, prompt.edit 훅의 경우 50밀리초 |
.catch 핸들러의 실행 시간 |
1초 |
모든 session.end 훅의 합계 |
SessionEnd 훅 예산만큼(변경하지 않으면 1.5초), 설정의 SessionEnd 훅이 완료된 시점부터 계산 |
$.process.run 타임아웃 |
기본값 30초, 최대 10분 |
$.process.run stdout 및 stderr |
각각 4 MiB. 잘린 경우 isStdoutTruncated 또는 isStderrTruncated가 true입니다. |
$.model.complete maxTokens |
기본값 1024, 최대 64,000 또는 모델의 출력 제한 |
$.fs.read 및 $.fs.write |
파일 하나당 4 MiB |
$.http.fetch 요청 본문 |
4 MiB(문자 수 기준). 본문이 이보다 큰 호출은 거부됩니다. |
$.http.fetch 응답 본문 |
4 MiB. text에는 처음 4 MiB가 담기며 나머지는 읽지 않습니다. Content-Length 헤더에 이보다 큰 값이 선언된 경우에는 대신 호출이 거부되며, 그 사유는 is over the 4194304-byte limit로 끝납니다. 단, 리디렉션 이후의 마지막 요청이 HEAD 메서드를 사용하는 경우는 예외입니다. HEAD 예외에는 Claude Code v2.1.296 이상이 필요합니다. |
리디렉션과 본문을 포함한 $.http.fetch 호출 하나 |
30초 |
$.http.fetch 호출 하나가 따르는 리디렉션 수 |
5 |
훅의 drop 사유 또는 config.set deny 사유 |
4,096자. 이보다 긴 사유는 끝부분이 잘리며, drop 또는 deny는 그대로 적용됩니다. 잘라내기에는 Claude Code v2.1.292 이상이 필요하며, 이전 버전에서는 대신 훅이 실패합니다. |
| 하나의 트리에 포함된 텍스트 | 처음 100,000자까지 그려집니다 |
Code의 language 또는 path, Select 옵션의 value, Client의 module |
10,000자. 이보다 길면 이를 반환한 ui.render 훅이 실패합니다. |
Link의 href |
2,048자. 이보다 길면 이를 반환한 ui.render 훅이 실패합니다. |
| 하나의 트리의 중첩 깊이 | 루트 요소 아래 32단계 |
| 하나의 트리에 포함된 요소 및 텍스트 자식 | 20,000 |
하나의 트리에 포함된 Raster 셀(각 Raster의 columns 곱하기 rows) |
262,144 |
하나의 트리에 포함된 모든 Image의 PNG 또는 RGBA 바이트 |
2 MiB |
$.store |
JSON 총 4 MiB |
$.session.messages() |
최신 4,096개 항목 |
$.ui.invalidate('ui.render') 다시 그리기 |
초당 10회로 제한되며, 터미널에서는 표시 중인 창, 확장된 밴드, 프롬프트 아래의 힌트 줄에 대해 초당 30회로 제한됩니다. 그보다 빨리 들어오는 호출은 하나로 병합됩니다. |
$.ui.toast |
{ timeoutMs }를 전달하지 않으면 4초 동안 표시됩니다. 클래식 렌더러에서는 mod의 새 토스트가 표시 중이거나 표시 대기 중인 이전 토스트를 대체할 수 있습니다. |
| 사용자가 요청하지 않았는데 열린 창 | 터미널 너비가 144열 이상일 때 배치되며, 사용자가 한 번 연 이후에는 110열 이상일 때 배치됩니다 |
| mod API 호출 인수의 중첩 깊이 | 28,000단계. 이를 넘으면 호출이 nesting deeper than 28000 levels is not supported로 끝나는 메시지와 함께 거부됩니다. Claude Code v2.1.299 이상이 필요합니다. |
turn.step의 훅과 같은 비동기 제너레이터 훅 외부에서 next에 전달되는 변경된 이벤트의 중첩 깊이 |
28,000단계. 이를 넘으면 next가 nesting deeper than 28000 levels is not supported로 끝나는 메시지와 함께 거부됩니다. Claude Code v2.1.299 이상이 필요합니다. |
ui.render, ui.resolve, 비동기 제너레이터 훅 외부에서 훅 반환 값의 중첩 깊이 |
28,000단계. 이를 넘으면 훅의 결과가 거부되며, 이를 보고하는 알림에 nesting deeper than 28000 levels is not supported가 포함됩니다. Claude Code v2.1.299 이상이 필요합니다. |
| 훅 모듈의 한 파일 안에서 서로 중첩된 함수, 블록, 루프 등의 범위 | 2,000 |
| 명령, 도구, 서브에이전트 유형 및 창 이름 | 문자, 숫자, _, -로 구성되며 최대 64자 |
하나의 claude plugin test 테스트 |
테스트에서 timeoutMs를 설정하지 않으면 5초 |
설정 및 환경 변수
다음은 mod에 영향을 주는 설정 및 환경 변수입니다. 위치 열은 각 항목을 어느 설정 파일 또는 환경에서 읽는지 나타냅니다.
| 이름 | 위치 | 기능 |
|---|---|---|
CLAUDE_CODE_PLUGIN_DIRS |
환경, 또는 ~/.claude/settings.json의 env |
플래그를 전달할 수 없는 앱을 위해 --plugin-dir와 같은 방식으로 로드할 플러그인 디렉터리입니다. 절대 경로를 :로 구분하며, Windows에서는 ;로 구분합니다. |
CLAUDE_CODE_PLUGIN_DIR_WATCH |
환경 | 1로 설정하면 장시간 실행되는 비대화형 세션이 저장 시 --plugin-dir mod를 다시 로드합니다 |
prependPlugins, appendPlugins |
관리형 설정. 관리형 설정이 없는 머신에서, 자격 증명이 Team 또는 Enterprise /login이 아닌 세션에서만 사용자 설정. |
acme-guard@acme-tools와 같은 플러그인 ID 목록입니다. prependPlugins의 mod는 사용자가 설치한 모든 mod보다 먼저 실행되고, appendPlugins의 mod는 그 후에 나열된 순서대로 실행됩니다. mod 실행 순서를 참조하세요. |
allowManagedModsOnly |
관리형 설정, 기본 제공 가드의 옵션으로 설정 | 조직의 mod로 간주되는 mod와 Claude Code에 기본 제공되는 mod만 훅을 실행합니다. 사용자의 설정 훅은 계속 실행됩니다. |
allowModsToOverrideDenyRules |
관리형 설정, 기본 제공 가드의 옵션으로 설정 | 사용자가 설치한 mod가 deny 규칙이 거부하는 도구 호출을 승인할 수 있도록 합니다 |
allowManagedHooksOnly |
관리형 설정 | 조직의 것이 아닌 훅과 설치된 mod를 차단합니다. 계속 실행되는 항목을 참조하세요. |
disableAllHooks |
모든 설정 파일 | 관리형 설정에서는 설치된 플러그인의 mod나 훅이 하나도 실행되지 않습니다. 사용자 본인의 설정에서는 조직이 관리하는 항목이 계속 실행됩니다. disableAllHooks를 참조하세요. |
disableSideloadFlags |
관리형 설정 | 시작 시 --plugin-dir 및 --plugin-url을 거부합니다 |
pluginConfigs |
사용자 또는 관리형 설정 | mod의 userConfig 값을 보관하며, acme-guard@acme-tools와 같은 플러그인 ID를 키로 사용합니다. --plugin-dir로 로드된 mod의 경우 first-mod@inline과 같이 이름과 @inline을 키로 사용합니다 |
sec-default@builtin은 Claude Code에 기본 제공되는 가드로, /plugin 및 디버그 로그에는 cc-plugin-sec-default로 표시됩니다. 관리형 설정이 있는 머신이거나 자격 증명이 Team 또는 Enterprise /login인 세션에서는, 사용자가 설치하는 모든 mod보다 먼저 로드됩니다. 관리형 prependPlugins가 설정된 경우, 이 가드는 해당 목록에 이름이 포함된 경우에만 나열된 위치에서 로드됩니다.
소스는 Claude Code 저장소의 mods/sec-default 디렉터리에 있습니다.
명령
다음 명령과 플래그는 mod를 로드하고, 검사하고, 테스트합니다. claude 명령은 셸에서 실행하고 / 명령은 Claude Code 프롬프트에서 실행합니다. 표에서 <directory>는 claude plugin validate ./first-mod처럼 직접 입력하는 경로를 나타냅니다. 대괄호는 선택적 인수를 표시합니다.
| 명령 | 기능 |
|---|---|
/plugin |
기본 제공되지 않는 mod가 로드되면 탭 아래에 1 mod active · first-mod와 같은 줄을 표시합니다 |
claude plugin validate <directory> |
플러그인의 매니페스트와 훅 모듈을 읽고 오류, 처리하는 이벤트, 수행하는 mods API 호출을 보고합니다. --strict는 경고를 오류로 처리하고 --json은 기계가 읽을 수 있는 보고서를 출력합니다. |
claude plugin test [directory] |
디렉터리 아래에서, 디렉터리를 지정하지 않은 경우 현재 디렉터리 아래에서 이름이 .test.ts 또는 .test.tsx로 끝나는 모든 파일을 실행합니다. 테스트가 실패하면 상태 1로 종료됩니다. |
claude --plugin-dir <directory> |
하나의 세션 동안 플러그인 디렉터리를 로드하고 저장할 때마다 훅 모듈을 다시 로드합니다. 여러 개를 로드하려면 플래그를 반복합니다. |
/reload-plugins |
실행하면 플러그인을 다시 로드합니다 |