Claude Code Mods 사용법: 첫 Mod 만들기·테스트·설치와 커뮤니티 예시 15선

Name

Soren Atelier

업데이트 2026. 10. 7.

Claude Code의 Mod는 Claude Code 안에서 실행되는 JavaScript 또는 TypeScript 함수로 만든 플러그인입니다. Mod는 패널이나 프롬프트 위의 한 줄을 그릴 수 있습니다. 즉시 실행되는 슬래시 커맨드를 추가할 수 있고, 도구 호출을 실행 전에 막거나 고쳐 쓸 수도 있습니다. Mods는 2026년 10월 1일 Claude Code 2.1.287과 함께 나왔고, 기본으로 켜져 있습니다.

목적에 맞는 가장 빠른 방법을 고르세요.

먼저 버전부터 확인하세요. claude --version이 2.1.287 이상을 출력해야 합니다. Desktop 앱은 자체 Claude Code를 내장하고 있고, 여기서는 2.1.286부터 Mods가 동작합니다. Code 탭에서 /status를 입력하면 지금 쓰는 버전을 볼 수 있습니다.

직접 테스트한 내용. 필자는 2026년 10월 7일 macOS의 Desktop 앱 Code 탭에서 Claude Code 2.1.293으로 Mod 3개를 만들었습니다. 명령 가드, 프롬프트 위 턴 미터, Python 작업용 /pyenv 커맨드입니다. 세 Mod 모두 claude plugin validate를 통과했고, claude plugin test로 돌린 자동 테스트 8개도 모두 통과했습니다. 가드는 핫 리로드를 켠 실제 세션에서도 돌려 봤습니다. 커뮤니티 관련 내용은 10월 1일부터 7일까지 Zenn, Qiita, note.com에 올라온 일본어 글 약 50편, 공식 Mods 문서 (opens in a new tab), 그리고 10월 6일 자 awesome-claude-code-mods (opens in a new tab) 카탈로그의 스캔 데이터를 바탕으로 했습니다.

Mod란 무엇이고, 언제 다른 방법을 써야 할까

Mods가 나오기 전에는 settings hook, 스킬, 상태 표시줄 스크립트, MCP 서버로 Claude Code를 바깥에서 확장했습니다. 차이는 코드가 실행되는 위치입니다. settings hook은 Claude Code가 바깥에서 실행하는 스크립트입니다. Mod의 함수는 Claude Code 자체 프로세스 안에서 실행됩니다. 그래서 Mod는 인터페이스에 그릴 수 있고, 나머지는 그릴 수 없습니다.

공식 개요 문서는 이 방법들을 대략 이렇게 비교합니다.

이름에 함정이 하나 있습니다. Mods 문서에서 "hook"은 Mod의 함수를 뜻하고, 예전 방식은 "settings hook"이라고 부릅니다. settings hook은 지금도 동작하고, 지원 중단되지도 않았습니다. 플러그인 하나에 Mod, 스킬, MCP 서버를 함께 넣을 수도 있습니다.

Mod가 동작하는 곳

훅은 거의 모든 곳에서 실행됩니다. 화면에 그리는 기능은 터미널과 Desktop 앱에서만 동작합니다.

이 표는 공식 개요 문서에서 가져왔습니다. 가드 Mod는 VS Code와 claude -p에서도 계속 보호해 주지만, 미터 Mod는 그릴 곳이 없다는 뜻입니다.

Claude Code가 두 벌 설치된 환경도 조심하세요. 일본 개발자 여러 명이 헷갈리는 validate 오류를 겪었습니다. Homebrew로 설치한 오래된 터미널 CLI가 Desktop 앱에 내장된 2.1.286과 함께 깔려 있었기 때문입니다. 보고된 CLI 버전은 2.1.226과 2.1.234였습니다. 사용하는 곳마다 버전을 확인하세요.

Mod의 파일 구성

작은 Mod는 파일 세 개면 됩니다.

safe-shell/
├── .claude-plugin/
│   └── plugin.json      name, version, description
└── hooks/
    ├── hooks.json       { "modules": ["./register.ts"] }
    └── register.ts      your code

register.ts는 register(on) 함수 하나를 export합니다. on(event, matcher, hook)을 호출할 때마다 훅이 하나씩 추가되고, 모든 훅은 같은 세 인자를 받습니다.

• $는 엔진입니다. 내 코드 바깥의 모든 것은 엔진을 거칩니다. $.ui.toast, $.process.run, $.state, $.model.complete가 그 예입니다.
• e는 이벤트입니다. 예를 들어 Claude가 곧 실행하려는 Bash 명령이 여기에 들어 있습니다.
• next(e)는 이벤트를 다른 Mod에 넘기고, 그다음 Claude Code에 넘깁니다. 호출하지 않고 반환하면 그 훅이 직접 답한 것이 됩니다. next({ ...e, command })를 호출하면 실제로 일어나는 일이 바뀝니다.

모듈에는 Node도 DOM도 없습니다. 이 제약 덕분에 Claude Code는 Mod가 호출하는 모든 것을 실행 전에 나열할 수 있습니다. 아무 Mod 폴더에서나 실행해 보세요.

claude plugin validate ./safe-shell

Mod 1: 파괴적인 명령을 막는 가드

auto 모드나 Bypass permissions 모드로 Claude를 실행하면, git reset --hard 앞에서 Claude를 멈춰 줄 장치가 없습니다. 이 Mod는 세 종류의 셸 명령을 거부하고, .env 파일이 대화에 들어오지 않게 막습니다.

import type { Register } from 'claude-code'
 
// Shell commands an agent should never run without a human typing them.
const BLOCKED: { pattern: RegExp; reason: string }[] = [
  {
    pattern: /\brm\s+-[a-zA-Z]*[rR][a-zA-Z]*\s+(\/|~|\$HOME)\/?\*?(\s|$)/,
    reason: 'recursive delete of / or the home folder',
  },
  {
    pattern: /\bgit\s+push\b.*(--force\b|--force-with-lease\b|\s-f\b).*\b(main|master)\b/,
    reason: 'force push to main or master',
  },
  {
    pattern: /\bgit\s+reset\s+--hard\b/,
    reason: 'git reset --hard throws away uncommitted work',
  },
]
 
// .env, .env.local, config/.env.production ... but not .env.example.
const isSecretEnvFile = (path: string) =>
  /(^|\/)\.env(\.[^/]+)?$/.test(path) && !/\.(example|sample|template)$/.test(path)
 
export const register: Register = on => {
  on('tool.call', { tool: 'Bash' }, ($, e, next) => {
    const hit = BLOCKED.find(rule => rule.pattern.test(e.command))
    if (hit === undefined) {
      return next(e)
    }
    $.ui.toast(`safe-shell blocked: ${hit.reason}`)
 
    return { deny: `safe-shell: blocked (${hit.reason}). Ask the user to run it themselves.` }
  }).catch(($, e, next) =>
    // Fail closed: if the guard itself breaks, refuse instead of letting the command through.
    next.called ? next(e) : { deny: 'safe-shell: the guard failed, so the command was not run.' },
  )
 
  for (const tool of ['Read', 'Edit', 'Write'] as const) {
    on('tool.call', { tool }, ($, e, next) =>
      isSecretEnvFile(e.file_path)
        ? { deny: `safe-shell: ${e.file_path} holds secrets and stays out of the conversation.` }
        : next(e),
    ).catch(($, e, next) =>
      next.called ? next(e) : { deny: 'safe-shell: the guard failed, so the file was not touched.' },
    )
  }
}

정규식보다 중요한 점이 두 가지 있습니다.

가드는 next를 호출하기 전에 판단합니다. next가 실행되면 명령도 이미 실행된 것입니다. 그 뒤에 deny를 반환해도 되돌릴 수 있는 것은 없습니다.

.catch가 가드를 fail closed로 만듭니다. 훅이 예외를 던지거나 10초 예산을 넘기면 엔진은 그 훅을 건너뜁니다. 그리고 건너뛴 가드는 명령을 그대로 통과시킵니다. next.called ? next(e) : deny 핸들러는 이때 통과 대신 거부를 택합니다. validate는 호출을 통과시킬지 결정하는 gating hook을 모두 나열하고, 각각에 .catch가 있는지 보여 줍니다. 다른 사람이 만든 가드를 볼 때 가장 먼저 확인할 부분입니다.

❯ ./register.ts hooks: tool.call{tool=Bash}, tool.call{tool=Read|Edit|Write}
❯ ./register.ts gating hook with .catch: tool.call{tool=Bash}
❯ ./register.ts gating hook with .catch: tool.call{tool=Read|Edit|Write}
❯ ./register.ts calls: $.ui.toast
✔ Validation passed

세션 없이 테스트하기

claude plugin test는 Mod의 *.test.ts 파일을 엔진 위에서 실행합니다. 세션, 로그인, 네트워크가 없어도 됩니다. 다만 테스트 키트에는 Mod 아래에 아무것도 없습니다. 그래서 테스트마다 Mod가 다음으로 넘기는 호출을 대신 받아 줄 스텁 훅을 등록합니다.

import { expect, test } from 'claude-code/testing'
 
const ran = { stdout: 'ran', stderr: '', interrupted: false }
 
test('blocks rm -rf on the home folder', async ($, on) => {
  on('tool.call', { tool: 'Bash' }, () => ({ result: ran }))
  const answer = await $.tool.call({ tool: 'Bash', command: 'rm -rf ~' })
  expect(answer.deny).toContain('recursive delete')
})
 
test('lets ordinary commands through', async ($, on) => {
  on('tool.call', { tool: 'Bash' }, () => ({ result: ran }))
  const answer = await $.tool.call({ tool: 'Bash', command: 'rm -rf ./build && python -m pytest -q' })
  expect(answer.deny).toBeUndefined()
})

전체 파일에는 테스트가 4개 있습니다.

(pass) blocks rm -rf on the home folder [16.23ms]
(pass) blocks a force push to main [7.73ms]
(pass) lets ordinary commands through [7.22ms]
(pass) keeps .env out of Read but allows .env.example [9.40ms]

 4 pass
 0 fail

필자의 첫 실행은 on("tool.call") after the test first called $ 오류로 실패했습니다. 스텁은 각 테스트의 맨 위, 첫 $ 호출보다 먼저 등록하세요.

실제 세션에서 확인한 동작

핫 리로드를 켠 상태에서 Claude에게 echo "the words git reset --hard inside an echo"를 실행하게 했습니다. 가드는 "blocked (git reset --hard throws away uncommitted work)"라는 메시지로 거부했고, 토스트 알림도 떴습니다. 그런데 이 echo는 무해했습니다. 패턴 매칭은 명령과 그 명령을 언급하는 텍스트를 구분하지 못합니다. 변수, 스크립트, alias에 숨은 명령도 놓칩니다. rafi-guard, delete-guard, board-guard처럼 비슷한 가드를 공개한 일본 개발자들도 두 문제를 모두 보고했습니다.

가드 Mod는 두 번째 안전망으로 다루세요. 절대 일어나면 안 되는 일은 권한 deny 규칙에도 넣어 두세요. 반대 방향도 알아 둬야 합니다. 공식 문서에 따르면 managed settings가 없는 개인 컴퓨터에서는 deny 규칙이 거부하는 호출을 Mod가 승인할 수 있습니다. Mod는 샌드박스에서 실행되지 않습니다. 사용자의 권한으로 실행됩니다.

Mod 2: 프롬프트 위의 미터

Mod가 가장 많이 그리는 곳은 프롬프트 위 밴드와 사이드 패널입니다. 10월 6일 카탈로그 스캔에서 Mod의 41%가 밴드에 그리고, 40%가 패널을 엽니다. 이번 Mod는 직전 턴의 소요 시간, 도구 호출 수, 토큰 수를 보여 주고, Hide 버튼으로 숨길 수 있습니다.

화면에 그릴 때 읽는 값은 $.state에 둡니다. 각 값은 작은 타입 파일에 선언합니다.

// types/index.d.ts, named in plugin.json as "types": "./types/index.d.ts"
export type TurnStats = {
  seconds: number
  tools: number
  inputTokens: number
  outputTokens: number
  model: string | null
}
 
declare module 'claude-code' {
  interface PluginState {
    'turn-meter': { last: TurnStats | null; isHidden: boolean }
  }
}

훅은 도구 호출을 세고, turn.complete에서 durationMs와 usage를 읽은 뒤 밴드를 그립니다.

import { atom, read, update } from 'claude-code'
import type { Register } from 'claude-code'
 
import type { TurnStats } from '../types'
 
const last = atom({ plugin: 'turn-meter', key: 'last' } as const, null)
const isHidden = atom({ plugin: 'turn-meter', key: 'isHidden' } as const, false)
 
const formatTokens = (n: number) => (n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n))
 
export const register: Register = on => {
  let tools = 0
 
  on('prompt.submit', ($, e, next) => {
    tools = 0
    return next(e)
  })
 
  on('tool.call', ($, e, next) => {
    // Count the main conversation's calls; subagents carry an agentId.
    if (e.agentId === undefined) tools += 1
    return next(e)
  })
 
  on('turn.complete', async ($, e, next) => {
    if (e.agentId !== undefined) return next(e)
    const usage = e.usage
    const stats: TurnStats = {
      seconds: Math.round(e.durationMs / 1000),
      tools,
      inputTokens: usage
        ? usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens
        : 0,
      outputTokens: usage?.output_tokens ?? 0,
      model: usage?.model ?? null,
    }
    await update($, last, () => stats)
    if (stats.seconds > 120) $.ui.toast(`That turn took ${stats.seconds}s`)
    return next(e)
  })
 
  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
    const stats = await read($, last)
    if (e.props.hasSurvey || stats === null || (await read($, isHidden))) return next(e)
 
    const { Box, Button, Text } = $.ui.resolve(e)
    const model = stats.model === null ? '' : ` · ${stats.model}`
    // The band is shared by every mod: keep what the mods beneath drew, then add a row.
    const below = await next(e)
 
    return (
      <Box flexDirection="column">
        {below}
        <Box>
          <Text dimColor>
            {`Last turn: ${stats.seconds}s · ${stats.tools} tool calls · ${formatTokens(stats.inputTokens)} in / ${formatTokens(stats.outputTokens)} out${model} `}
          </Text>
          <Button key="hide" label="Hide" onPress={() => update($, isHidden, () => true)} />
        </Box>
      </Box>
    )
  })
}

테스트에서는 터미널과 Desktop 양쪽에서 밴드가 이렇게 나옵니다.

Last turn: 42s · 0 tool calls · 18.2k in / 800 out · claude-opus-5-5 [ Hide ]

만들면서 알게 된 점 세 가지입니다.

• 그리는 값은 모듈 변수가 아니라 $.state에 두세요. 핫 리로드는 register를 다시 실행해 변수를 초기화하지만, $.state는 그대로 남습니다. /clear를 하면 처음부터 다시 시작하므로, 그보다 오래 남겨야 하는 값은 session.end에서 $.store에 쓰세요.
• 밴드는 모든 Mod가 함께 씁니다. next(e)를 호출하고 그 결과를 내 Box 안에 넣으세요. 그러지 않으면 다른 Mod의 줄을 전부 가리게 됩니다. note.com의 한 저자도 이 구조를 알기 전까지 밴드 하나가 다른 Mod에 가려지는 문제를 겪었습니다.
• Text 요소는 key를 유지하지 않습니다. 테스트에서는 표시된 문구로 찾으세요. ui.find({ type: 'Text', text: /Last turn/ })처럼 씁니다.

Mod 3: Claude가 엉뚱한 Python을 실행할 때 쓰는 /pyenv

데이터 사이언스용 Mod를 찾아보다가 빈 곳을 발견했습니다. 10월 6일 스캔에 잡힌 Mod 2,690개 중 이름이나 설명에 Jupyter, pandas, DataFrame, Polars, venv, conda를 언급한 것은 하나도 없습니다.

이 Mod가 해결하는 문제는 데이터 작업에서 흔합니다. Claude의 Bash 도구는 PATH에서 가장 먼저 찾은 python3를 실행합니다. 그런데 그것이 프로젝트 환경이 아닌 경우가 많습니다. 필자의 컴퓨터에서 환경 확인용 프로브 스크립트를 돌리면 이렇게 출력됩니다.

python: /Users/<you>/.local/bin/python3 (3.14.2)
env: none (system or tool-managed Python)
pandas: 3.0.1
numpy: 2.4.2
polars: not installed
matplotlib: 3.11.0
pygwalker: not installed

활성화된 가상 환경이 없었습니다. 이 상태에서 Claude가 pip install을 실행했다면 전역 인터프리터에 패키지가 설치됐을 것입니다.

/pyenv 커맨드는 이 프로브를 실행하고 두 부분으로 답합니다. text는 사용자가 보는 줄입니다. context는 모델만 읽는 메모입니다. 덕분에 Claude는 사용자가 다시 알려 주지 않아도 다음 Bash 호출에서 어떤 인터프리터를 쓰는지 압니다.

import type { Register } from 'claude-code'
 
// Reads package versions from metadata instead of importing them, so it stays fast.
const PROBE = `
import os, sys
from importlib.metadata import PackageNotFoundError, version
env = os.environ.get("VIRTUAL_ENV") or os.environ.get("CONDA_PREFIX") or "none (system or tool-managed Python)"
print(f"python: {sys.executable} ({sys.version.split()[0]})")
print(f"env: {env}")
for name in ("pandas", "numpy", "polars", "matplotlib", "pygwalker"):
    try:
        print(f"{name}: {version(name)}")
    except PackageNotFoundError:
        print(f"{name}: not installed")
`
 
export const register: Register = on => {
  on('session.start', async ($, e, next) => {
    await $.command.register({
      name: 'pyenv',
      description: "Show which Python, environment and data packages this session's shell uses",
    })
    return next(e)
  })
 
  on('command.run', { command: 'pyenv' }, async $ => {
    try {
      const probe = await $.process.run(['python3', '-c', PROBE], { timeoutMs: 15_000 })
      if (probe.exitCode !== 0) {
        return { text: `pyenv: python3 exited with ${probe.exitCode}: ${probe.stderr.trim().slice(0, 300)}` }
      }
      const report = probe.stdout.trim()
      // `text` is the row you see; `context` is a note only the model reads.
      return {
        text: report,
        context: [`Python environment of this session's shell, from /pyenv:\n${report}`],
      }
    } catch (error) {
      return { text: `pyenv: could not run python3 (${String(error).slice(0, 200)})` }
    }
  })
}

Mod의 슬래시 커맨드는 모델 턴 없이 함수를 바로 실행합니다. Claude가 작업 중일 때도 실행됩니다. $.process.run은 셸을 거치지 않고 인자 목록을 받습니다. timeoutMs를 지정하지 않으면 30초 뒤에 타임아웃됩니다.

그렇다면 $.process.run은 Claude의 Bash 도구와 같은 PATH를 볼까요? 커뮤니티의 한 저자가 Mod가 띄운 프로세스에서 nvm의 node를 찾지 못했다고 보고해서, 임시 프로브 Mod로 확인해 봤습니다. 필자의 Desktop 세션에서는 그냥 호출한 $.process.run이 Bash 도구와 똑같은 PATH를 받았고, python3도 같은 것을 가리켰습니다. 반면 로그인 셸 zsh -lc를 거쳐 프로브를 실행하면 틀린 답이 나왔습니다. python.org의 3.10.9를 가리켰습니다. 비대화형 로그인 셸은 ~/.zshrc를 건너뛰는데, PATH 추가 설정은 대부분 그 파일에 있기 때문입니다. 그냥 호출하는 방식을 유지하세요. 내 컴퓨터에서 결과가 이상해 보이면 Claude Code 프롬프트에서 !which python3를 입력해 비교해 보세요.

테스트하면서 함정을 하나 더 발견했습니다. $.process.run과 $.command.register 같은 $ 호출에도 스텁이 필요하고, $ 호출용 스텁은 { value: ... } 형태로 응답해야 합니다. 결과를 그대로 반환하면 테스트 키트가 받아들이지 않습니다.

분석 대부분을 스크립트가 아니라 노트북에서 한다면 이 방법에는 한계가 있습니다. Claude Code는 .ipynb 파일을 JSON으로 편집할 뿐, 실행 중인 커널을 보지 못합니다. RunCell (opens in a new tab)은 셀을 실행하고 그 출력을 직접 읽는 노트북 에이전트라서 그런 작업에 더 잘 맞습니다.

Mod를 Claude에게 만들게 하기

이 코드를 전부 손으로 쓸 필요는 없습니다. 세션에서 "5시간 사용량을 프롬프트 위에 보여 주는 Mod를 만들어 줘"처럼 요청하면 됩니다. Claude는 내장 plugin-authoring 스킬을 불러와 ~/.claude/dev-mods/<session-id>/에 파일을 씁니다. 첫 파일을 쓸 때 "Enable hot reloading for this session?"이라는 질문이 한 번 나옵니다. 동의하면 Claude의 턴이 끝날 때마다 수정 사항이 다시 로드됩니다. 위의 Mod 3개도 이렇게 만들고 불러왔습니다.

문서와 커뮤니티가 덧붙이는 내용입니다.

• 폴더는 영구적인 위치에 복사해 두세요. Qiita와 Zenn의 저자들은 dev-mods 폴더가 약 30일 뒤 오래된 세션과 함께 정리된다고 보고합니다.
• 개발할 때는 claude --plugin-dir ./my-mod를 쓰세요. 설치한 Mod는 캐시된 사본으로 실행되므로, 원래 폴더를 고쳐도 플러그인을 업데이트하기 전까지는 아무것도 바뀌지 않습니다.
• Desktop 앱에는 실행 플래그를 넘길 수 없습니다. ~/.claude/settings.json의 env 블록에 CLAUDE_CODE_PLUGIN_DIRS를 설정하세요. 이 값은 프로젝트 설정에 넣으면 무시됩니다.
• /plugin을 실행하세요. 1 mod active · safe-shell 같은 흐린 줄이 보이면 Mod가 로드된 것입니다.
• 만드는 동안에는 claude --debug로 시작하세요. 디버그 로그에는 건너뛴 훅과 엔진이 거부한 그리기 작업이 모두 남습니다.

살펴볼 만한 커뮤니티 Mod 15선

스타 316개를 받은 awesome-claude-code-mods (opens in a new tab) 카탈로그는 출시 5일 뒤인 10월 6일에 저장소 1,265개에 있는 공개 Mod 2,690개를 스캔했습니다. 스캔 데이터를 보면 사람들이 무엇을 만드는지 알 수 있습니다.

• 68%는 슬래시 커맨드를 추가합니다.
• 53%는 도구 호출에 훅을 겁니다.
• 41%는 프롬프트 위에 그리고, 40%는 패널을 엽니다.
• 40%는 프로세스를 실행하고, 12%는 모델을 호출하고, 11%는 네트워크를 씁니다.

아래 15개를 보면 그 범위를 알 수 있습니다. 스타 수는 2026년 10월 7일 기준입니다.

Anthropic도 claude-code-playground (opens in a new tab)에 샘플 3개를 공개했습니다. token-weather, blast-radius, replay-theater입니다. /diff를 포함한 내장 Mod의 소스는 claude-code 저장소 (opens in a new tab)에 있습니다.

커뮤니티에서 자리 잡은 베스트 프랙티스

출시 첫 주에 일본 개발자들만 해도 글을 약 50편 올렸습니다. 동작하는 Mod, 측정 결과, 실패 보고가 담긴 글입니다. 그중 반복해서 나온 습관은 다음과 같습니다.

1. 설치하기 전에 Mod를 읽습니다. 저장소를 clone하고 claude plugin validate를 실행한 뒤 hooks:와 calls: 줄을 읽습니다. $.process, $.http, $.fs.write, $.env.get, $.model이 나오는 곳은 소스까지 읽으세요. 업데이트할 때마다 다시 validate하세요. 통과했다는 것은 엔진이 코드를 불러올 수 있다는 뜻이지, 코드가 안전하다는 뜻이 아닙니다.
2. 가드는 next 전에 판단하고 fail closed로 둡니다. 지켜보기만 하는 Mod는 .catch(($, e, next) => next(e))로 fail open하게 두세요. 그래야 미터의 버그가 작업을 막지 않습니다.
3. 기다릴 때는 $ 호출 안에서 기다립니다. 훅에는 자기 몫의 시간 10초가 주어집니다. 진행 중인 $.process.run이나 $.ui.ask는 이 시간에 포함되지 않지만, 직접 만든 promise는 포함됩니다.
4. $를 저장하거나 구조 분해하지 않습니다. 파일 최상위에 선언한 함수에만 넘기세요. 여러 저자의 Mod가 이 문제를 고치기 전까지 오류 메시지도 없이 로드되지 않았습니다.
5. 프롬프트 캐시를 신경 씁니다. 세션 중간에 모델을 바꾸거나 요청마다 시스템 프롬프트를 바꾸면 캐시가 버려집니다.
6. e.surface로 분기합니다. Svg는 Desktop 앱에서만 그려지고, Raster와 Image는 터미널에서만 그려집니다.
7. 팀에서 쓸 때는 버전을 고정합니다. API는 얼리 액세스 단계라서 릴리스마다 바뀝니다. 출시 뒤 나온 2.1.288부터 2.1.293까지 릴리스 6개 중 5개가 Mod 동작을 바꾸거나 고쳤습니다.

비밀 값 마스킹은 경계해야 할 사례입니다. note.com의 한 저자는 도구 출력에 들어 있는 API 키를 Claude가 보기 전에 바꿔치기하는 Mod를 만들었습니다. 그래도 Claude는 실패한 편집을 od -c로 디버깅하면서 원래 값을 그대로 출력했습니다. 파일 전체를 쓰는 Write는 진짜 키 자리에 플레이스홀더를 덮어썼습니다. 끝까지 막아 낸 것은 그 파일에 건 권한 deny 규칙뿐이었습니다. 화면에 보이는 내용을 바꾸는 Mod는 모델에게서 아무것도 숨기지 못합니다.

자주 겪는 문제

Mod 공유하기

.claude-plugin/ 안에서 plugin.json 옆에 marketplace.json을 둡니다.

{
  "name": "my-mods",
  "owner": { "name": "you" },
  "plugins": [{ "name": "safe-shell", "source": "./" }]
}

폴더를 GitHub에 push하세요. 그러면 누구나 터미널 세션에서 설치할 수 있습니다.

/plugin install safe-shell --marketplace you/safe-shell

Desktop 앱의 로컬 세션과 SSH 세션에서는 +, Plugins, Add plugin 순서로 들어갑니다. 저장소에 claude-code-mod 토픽을 붙여 두면, 보통 다음 push 후 몇 시간 안에 커뮤니티 카탈로그에 올라갑니다.

FAQ

관련 가이드

• Claude Code Desktop에서 Bypass permissions 켜는 법
• Claude Code AGENTS.md 사용법: CLAUDE.md 차이, 4가지 로딩 모드, Codex·OpenCode와 공유
• Claude Code 루틴 사용법: AI 에이전트 cron 작업과 자동 트리거
• Claude Agent SDK (TypeScript)로 Claude Code 스타일의 AI 에이전트 만들기
• OpenCode 사용법 가이드: 시작 방법, 실전 팁 7가지, Oh My OpenCode와 함께 쓰는 법