모드 만들기

• Claude에게 작성하도록 요청: Claude Code 세션에서 원하는 것을 설명하세요
• 직접 작성: 튜토리얼을 따르세요 모드의 코드가 어떻게 작동하는지 배우세요. Node.js, 번들러 또는 빌드 단계가 필요하지 않습니다. Claude Code는 .js 및 .ts 파일을 직접 로드하기 때문입니다.

​

Claude에게 모드 작성 요청

​

다른 세션에서 모드 사용

• 시작하는 세션에서: 셸에서 claude --plugin-dir ~/mods/git-branch를 실행하세요
• 다른 사람들을 위해: 마켓플레이스에 추가하여 설치할 수 있도록 하세요

​

Claude가 작성한 모드가 로드될 수 없는 세션

• 승인할 사람이 없음: claude -p 실행 또는 dontAsk 모드와 같이 세션이 프롬프트를 표시할 수 없습니다
• 작업 공간을 신뢰하지 않음: 디렉토리에 대한 신뢰 프롬프트를 수락하지 않았습니다
• 모드가 중지됨: --safe-mode 또는 --bare로 시작했거나, disableAllHooks를 설정했거나, 조직의 관리 설정이 차단했습니다

​

모드 직접 작성

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

• plugin.json: 플러그인의 매니페스트
• hooks.json: 코드 파일을 가리킵니다
• register.js: 코드, hooks 모듈이라고 불립니다

mkdir -p first-mod/.claude-plugin first-mod/hooks

New-Item -ItemType Directory -Force first-mod\.claude-plugin, first-mod\hooks

{
  "name": "first-mod",
  "version": "0.1.0",
  "description": "Counts Claude's tool calls, shows the count beside the spinner, and adds a /tally command",
  "author": { "name": "Your Name" }
}

{
  "description": "The first-mod hooks module",
  "modules": ["./register.js"]
}

// The count, shared by the hooks below
let calls = 0

// Claude Code calls this once when the mod loads
export function register(on) {
  // Runs when the session starts, before your first prompt
  on('session.start', async ($, e, next) => {
    // Add the /tally command
    await $.command.register({
      name: 'tally',
      description: 'Show how many tool calls Claude has made',
    })
    // Let the session start as usual
    return next(e)
  })

  // 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 when you type /tally, and only then, because of the matcher
  on('command.run', { command: 'tally' }, async () => {
    // The text to print in the transcript
    return { text: 'Claude has made ' + calls + ' tool calls since this mod loaded' }
  })

  // 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 + '…' } })
  })
}

claude --plugin-dir ./first-mod

claude -p "/tally" --plugin-dir ./first-mod

first-mod: Claude has made 0 tool calls since this mod loaded

  // 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: ' · tools used: ' + calls + '…' } })
  })

​

예제 모드가 어떻게 작동하는지

• mods API, $라고 이름 지어짐: 모드가 자신 외부에 도달하기 위해 호출할 수 있는 모든 메서드. $.ui 및 $.command와 같은 네임스페이스에 있습니다
• 이벤트, e라고 이름 지어짐: 이벤트의 입력. 도구 호출의 이름 및 인수와 같은 일반 데이터
• 다음 핸들러, next라고 이름 지어짐: 이벤트를 다른 모드로 전달한 다음 Claude Code의 자체 동작으로 전달하고 결과를 반환하는 함수

• 관찰: session.start hook은 명령을 등록하고, tool.call hook은 호출을 세고 다시 그리도록 요청합니다. 둘 다 next(e)를 반환하므로 세션이 시작되고 도구가 평소대로 실행됩니다.
• 답변: command.run hook은 자신의 결과를 반환하고 next를 호출하지 않습니다. on의 두 번째 인수인 { command: 'tally' }는 matcher라고 불리는 필터이므로 hook은 /tally에 대해서만 실행됩니다.
• 다시 쓰기: ui.render hook은 e의 복사본과 함께 next를 호출하며, 그 suffix는 개수를 보유하므로 Claude Code는 단어 뒤에 텍스트가 있는 일반적인 스피너를 그립니다

​

모드에서 계속 작업하기

​

Claude로 모드 변경하기

claude --plugin-dir ./first-mod

​

버전의 타입 정의 가져오기

​

Claude Code가 모드에서 읽는 것 확인하기

claude plugin validate ./first-mod

  ❯ ./register.js hooks: session.start, tool.call, command.run{command=tally}, ui.render{component=Spinner}
  ❯ ./register.js calls: $.command.register, $.ui.invalidate

✔ Validation passed

• 각 mods API 호출을 완전히 철자하세요: $, 네임스페이스, 메서드. 예를 들어 $.store.get('notes'). $를 동일한 파일의 최상위 수준에서 선언된 함수로 전달할 수 있으며, loadNotes라는 함수의 경우 calls: 줄은 $.store.get (via loadNotes)를 읽습니다. $를 메서드, 함수 내부에서 정의된 함수, 또는 파일의 다른 부분에서 가져온 함수로 전달하면 검증이 실패합니다. $.state가 사용하는 read 및 update 함수는 이를 취할 수 있는 가져오기입니다. $ 또는 네임스페이스 중 하나를 변수에 할당하거나, 구조 분해하거나, 계산된 이름으로 인덱싱하지 마세요. const ui = $.ui는 $.ui is used as a value로 실패합니다.
• 각 on 호출에서 이벤트 이름을 문자열 리터럴로 작성하세요. 예를 들어 'tool.call'. 변수 또는 이름 목록에 대한 루프는 the event name passed to on() is not a string literal로 실패합니다.
• register 내부에서 on이라는 두 번째 변수 또는 매개변수를 선언하지 마세요. 검증은 "on" is declared again (shadowed)로 실패합니다.
• 상대 경로로 플러그인 디렉토리 내 파일에서만 가져오세요. 허용되는 유일한 베어 가져오기는 타입 및 몇 가지 도우미를 위한 claude-code입니다.
• 파일의 맨 위에 import 선언을 사용하세요. 예를 들어 import { name } from './file.js'. 동적 import()는 a dynamic import(); a hooks module imports its own files with an import declaration로 실패합니다.
• 모든 파일을 ES 모듈로 작성하세요. import를 사용하고 require는 사용하지 마세요. 참조는 Claude Code가 로드하는 파일 확장자를 나열합니다.

​

모드 테스트하기

import { expect, test } from 'claude-code/testing'

test('/tally reports the tool calls the mod has seen', async ($, on) => {
  // Answer each tool call in Claude Code's place, so no tool runs
  on('tool.call', () => ({ result: 'ok' }))

  // Raise two tool calls, which the mod's tool.call hook counts
  await $.tool.call({ tool: 'Bash', command: 'ls' })
  await $.tool.call({ tool: 'Read', file_path: 'README.md' })

  // Run /tally and check the text its hook returns
  const answer = await $.command.run({ command: 'tally', args: '' })
  expect(answer.text).toBe('Claude has made 2 tool calls since this mod loaded')
})

claude plugin test

tests/first-mod.test.ts:
(pass) /tally reports the tool calls the mod has seen [22.87ms]

 1 pass
 0 fail
Ran 1 test across 1 file. [0.19s]

​

모드 공유

​

다음 단계

• 인터페이스에 그리기: 창을 열고, 프롬프트 위에 그리고, 버튼 및 텍스트 필드 추가
• 이벤트에 반응: 도구 호출, 프롬프트 및 턴 hook
• mods API 사용: 명령 및 도구 추가, 모델 호출, 타이머에서 작업 실행
• 모드 테스트: Claude Code가 답변할 것을 스텁하고, 타이머 및 그리기 테스트
• 모드 문제 해결: 모드가 아무것도 하지 않는 이유 및 디버그 로그
• 내장 모드의 소스 읽기: 완전한 플러그인. 각각 hooks 모듈 및 테스트 포함