SpyBara
Go Premium

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

This page contains 105 additions and 97 deletions.

2026
Fri 2 22:59 Sat 3 23:57 Sun 4 23:58 Tue 6 23:59 Wed 7 23:59 Thu 8 22:58 Fri 9 23:02 Sat 10 23:01 Sun 11 23:57 Wed 14 22:58 Thu 15 23:58 Fri 16 22:59 Mon 19 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Sun 25 23:58 Mon 26 22:57 Tue 27 22:59

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로 지정된 types/index.d.ts mod가 $.state를 사용하거나 mods API에 네임스페이스를 추가하는 경우 PluginState 값과 mod가 추가하는 모든 네임스페이스를 선언합니다
이름이 .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 훅에서 다음 필드를 읽어 서브에이전트의 호출과 메인 대화의 호출을 구분하고, 조직이 커넥터 도구에 대해 승인을 요구하는지 확인할 수 있습니다.

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 이상이 필요합니다.

명령과 구성

명령 및 구성 이벤트는 명령이 실행되거나 목록에 표시될 때, 그리고 /config 행이 표시되거나 변경될 때 발생합니다.

이벤트 발생 시점 훅이 반환할 수 있는 값
command.run 명령이 실행되기 직전 { text }, {} 또는 next(e)
command.describe 명령 목록을 위해 명령마다 한 번 { description, argumentHint, isHidden }
config.set /config 행이 변경되기 직전 next({ ...e, value }) 또는 { deny: reason }
config.describe /config 행마다 한 번 { label, description, isHidden }

턴

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

이벤트 발생 시점 훅이 반환할 수 있는 값
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입니다. 모델을 선택하려면 next({ ...e, model }), 또는 { deny: reason }

Claude가 SendMessage 도구로 서브에이전트를 재개할 때는 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, onPress, hotkey, plain, dimColor, autoFocus, action, hover ✓ ✓ ✓
Link href, label. 제한 사항을 참조하십시오. ✓ ✓ ✓
Code source, language, path, startLine, format, wrap ✓ ✓ ✓
Markdown text, key, dimColor, onLinkPress, pressableLinks ✓ ✓ ✓
Input key, label, placeholder, value, submitLabel, 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를 지정하면 나중의 버튼이 이를 가져갑니다

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를 눌러 버튼을 누릅니다
  • Code: language, path, startLine, format, wrap. 따라서 코드는 색상이나 줄 번호 없이 그려지며, format: 'diff' 블록은 diff의 원시 텍스트를 표시합니다
  • Input 및 Select: autoFocus
  • Svg: 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 이상이 필요합니다. 이전 릴리스에서는 단계 이름을 사용하는 트리 대신 Claude Code가 사이트의 자체 버전을 그립니다.

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를 설정한 트리 대신 Claude Code가 사이트의 자체 버전을 그립니다.

bold를 weight로 대체하기

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

v2.1.299 이전 릴리스에서는 weight를 설정한 트리가 그려지지 않으며, 대신 Claude Code가 사이트의 자체 버전을 그립니다. Text에 bold와 weight를 모두 설정하면 bold는 효과가 없습니다.

제한

훅 및 mod API 호출은 시간 및 크기 제한 내에서 실행됩니다. Claude Code는 시간 제한을 초과한 훅을 건너뜁니다.

제한 값
하나의 이벤트에 대한 훅 자체의 실행 시간(next 내부 시간 또는 $.clock.sleep을 제외한 mod API 호출 시간은 포함하지 않음) 10초, prompt.edit 훅의 경우 50밀리초
.catch 핸들러의 실행 시간 1초
모든 session.end 훅의 합계 SessionEnd 훅 예산만큼(변경하지 않으면 1.5초), 설정의 SessionEnd 훅이 완료된 시점부터 계산
$.process.run 타임아웃 기본값 30초, 최대 10분
$.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자. 이보다 길면 Claude Code가 해당 위치를 자체 버전으로 그립니다.
Link의 href 2,048자. 이보다 긴 href가 있으면 트리 전체가 그려지지 않습니다.
$.store JSON 총 4 MiB
$.session.messages() 최신 4,096개 항목
$.ui.invalidate('ui.render') 다시 그리기 초당 10회로 제한되며, 터미널에서는 표시 중인 창, 확장된 밴드, 프롬프트 아래의 힌트 줄에 대해 초당 30회로 제한됩니다. 그보다 빨리 들어오는 호출은 하나로 병합됩니다.
$.ui.toast { timeoutMs }를 전달하지 않으면 4초 동안 표시됩니다
사용자가 요청하지 않았는데 열린 창 터미널 너비가 144열 이상일 때 배치되며, 사용자가 한 번 연 이후에는 110열 이상일 때 배치됩니다
훅 모듈의 한 파일 안에서 서로 중첩된 함수, 블록, 루프 등의 범위 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 실행하면 플러그인을 다시 로드합니다