ilhae.ai

EBOOK · 2026년 11월 4일

Claude Code Mods 사용법: 데스크톱 앱 입문 가이드 2026

김재우 지음 · 11장 · 읽는 시간 약 2시간

Claude Code의 Mods(모드)를 데스크톱 앱의 Code 탭에서 쓰기 위한 입문서입니다. Mod를 만드는 법(plugin.json·hooks.json·register.tsx 3개 파일), 페인·밴드·상태 줄·토스트를 띄우는 법, 마켓플레이스에서 설치하는 법과 배포하는 법을 공식 문서에 따라 차례대로 정리했습니다.

처음부터 읽기

웹 뷰어에서만 읽을 수 있는 책입니다. 본문 복사·인쇄·저장은 막혀 있어요.

목차

  1. 1장. Claude Code의 Mods란 ― 할 수 있는 것·그릴 수 있는 위치·데스크톱 앱에서 돌아가는 조건

    Claude Code의 Mods(모드)는 Claude Code 안에서 돌아가는 JavaScript나 TypeScript 함수입니다. 화면에 나만의 영역을 추가하거나 Claude의 도구 호출에 끼어들 수 있는 플러그인이죠. 그린 내용은 터미널의 claude와 데스크톱 앱의 Code 탭에서만 보입니다. 데스크톱 앱에서는…

    읽기
    절 9개 보기
    • Mods는 무엇을 하나
    • 할 수 있는 것
    • 그릴 수 있는 위치·띄울 수 있는 것
    • 어디서 돌아가나
    • 데스크톱 앱에서 돌아가는 조건
    • 데스크톱 앱에서 쓸 수 있는 컴포넌트
    • 끄는 법
    • Mod 실물 둘러보기
    • 이 책을 읽는 법

  2. 2장. Claude Code Mod 만드는 법 ― 데스크톱 앱에서 돌아가는 최소 3개 파일

    Claude Code의 Mod는 .claude-plugin/plugin.json·hooks/hooks.json·hooks/register.tsx 이 3개 파일만 있으면 만들 수 있습니다. Node.js도 빌드도 필요 없습니다. Claude Code가 .js·.ts·.tsx를 그대로 읽어 들이니까요. 데스크톱 앱과…

    읽기
    절 1개 보기
    • 3개 파일 배치

  3. 3장. Claude Code Mod로 페인(대화 옆 영역) 만들기 ― $.ui.open과 ui.render

    Mod로 페인을 띄우려면 두 단계를 거칩니다. $.ui.open({ id })로 열고, ui.render의 { component: 'Pane' }에서 내용을 반환합니다. 열기만 해서는 아무것도 그려지지 않습니다. 연 다음에 Claude Code가 ui.render를 호출해서 "이 페인에 뭘 그릴까?"라고 물어 옵니다.…

    읽기
    절 11개 보기
    • 페인이란
    • 최소 페인
    • 열기: $.ui.open
    • 커맨드로 열기
    • 그리기: ui.render와 Pane
    • 다시 그리기가 도는 방식
    • 폭에 맞추기
    • 값 유지하기: 저장 위치 3가지
    • 데스크톱에서 그릴 수 있는 것
    • 키보드
    • 실제 예 보기

  4. 4장. Claude Code Mod로 프롬프트 위에 한 줄 띄우기 ― 밴드·상태 줄·토스트 만드는 법

    프롬프트 바로 위에 항상 한 줄을 띄우고 싶다면 ui.render를 { component: 'AbovePrompt' }로 받아 트리를 반환합니다(밴드). 프롬프트 아래에 문장 한 줄만 띄우려면 $.ui.status(text), 몇 초 뒤 사라지는 알림이라면 $.ui.toast(text)를 씁니다. 뒤의 두 가지는…

    읽기
    절 7개 보기
    • 세 가지의 차이
    • 밴드(프롬프트 위의 띠)
    • 상태 줄
    • 토스트
    • 대화 속에 흐린 줄 남기기
    • 스피너에 한마디 덧붙이기
    • 무엇을 고를까

  5. 5장. Claude Code Mod가 에러 없이 아무것도 그리지 않을 때·로드되지 않을 때 볼 곳

    Mod가 에러도 없이 아무 일도 하지 않는다면 원인은 대개 셋 중 하나입니다. (1) 정적 검사에서 탈락해 Mod 전체가 로드되지 않았다. (2) 훅 실행 환경에 없는 것을 써서 훅이 건너뛰어졌다. (3) 반환한 트리가 컴포넌트 규칙에 맞지 않아 Claude Code가 기본 표시를 그렸다. 먼저 claude…

    읽기
    절 9개 보기
    • 왜 조용히 사라지나
    • 한눈에 보기
    • 첫 단계: claude plugin validate
    • 1. 정적 검사에서 탈락했다
    • 2. 훅 실행 환경에 없는 것을 썼다
    • 3. 반환한 트리가 컴포넌트 규칙에 맞지 않는다
    • 이유가 적힌 한 줄 찾기
    • 애초에 Mod를 로드할 수 있는 상태인가
    • 정리

  6. 6장. 터미널에서 만든 Claude Code Mod를 데스크톱 앱에서 열면 깨진다 ― 페인이 안 열림·Svg가 쪼그라듦·깜박임

    터미널에서 잘 돌던 Mod를 데스크톱 앱에서 열면 자주 부딪히는 문제가 다섯 가지 있습니다. 실행할 때 연 페인이 안 나온다(사람의 조작이 계기가 아닌 open은 144열부터), 16진수 색이 밝은 테마에서 안 읽힌다, Raster가 그려지지 않는다, Svg가 300×150으로 쪼그라든다, isInteractive…

    읽기
    절 8개 보기
    • 1. 실행할 때 연 페인이 안 나온다
    • 2. 16진수 색이 밝은 테마에서 안 읽힌다
    • 3. Raster가 그려지지 않는다·surface 판별이 틀린다
    • 4. Svg가 작은 사각형으로 쪼그라든다
    • 5. isInteractive Svg가 1초마다 검게 깜박인다
    • 그 밖에 걸리는 두 가지
    • 데스크톱을 열지 않고 Svg 확인하기
    • 정리

  7. 7장. Claude Code Mod가 Windows에서 안 돌아가는 원인 ― $.process의 tail·date·open·osascript와 나지 않는 소리

    Mac이나 Linux에서 만든 Mod가 Windows에서 안 돌아간다면 대부분 $.process로 Windows에 없는 프로그램(tail·date·open·osascript·afplay·xdg-open 등)을 실행하기 때문입니다. $.process.run은 셸을 거치지 않으므로 start나 dir 같은 cmd 내장…

    읽기
    절 9개 보기
    • 얼마나 자주 걸리나
    • $.process.run은 셸을 쓰지 않는다
    • Windows에 없는 프로그램과 대안
    • OS 판별하기
    • 기본 앱으로 파일 열기
    • 소리가 안 난다: $.audio.play는 Windows에서 무음인 채로 성공한다
    • PowerShell을 띄운다는 것의 무게
    • Windows의 소소한 차이
    • 정리

  8. 8장. Claude Code Mod의 버튼으로 Claude에게 요청하면 첫 번째가 먹히지 않는다($.prompt.submit을 둘 곳)

    Mod 버튼의 onPress나 커맨드 안에서 $.prompt.submit을 호출하면 Claude가 움직이지 않을 때가 있습니다. 제가 쓰는 버전에서는 버튼을 누른 이벤트 안에서 $.prompt.submit을 호출하면 이벤트가 끝나면서 버려졌고 에러도 나지 않았습니다. 버튼에서는 보낼 내용을 변수에 담아 두기만 하고…

    읽기
    절 9개 보기
    • 증상
    • 공식 문서에 적힌 내용
    • 제 환경에서 일어난 일
    • 해결책: 누를 때는 '담아 두기만', 전송은 타이머가
    • 같은 이유로 외부 프로세스도 타이머에서
    • 타이머는 하나만
    • 다시 그리기가 너무 잦으면 누르고 있는 버튼이 새로 만들어진다
    • 보내는 문장 쓰는 법
    • 정리

  9. 9장. Claude Code Mod를 마켓플레이스로 배포하기·설치하기 ― marketplace.json과 /plugin install

    Mod도 플러그인이므로 배포하는 법도 설치하는 법도 플러그인과 같습니다. 배포하는 쪽은 저장소에 .claude-plugin/marketplace.json을 두고 push하면 끝입니다. 설치하는 쪽은 /plugin marketplace add owner/repo로 마켓플레이스를 추가한 뒤 /plugin install…

    읽기
    절 8개 보기
    • 용어 정리
    • 배포하기: marketplace.json 두기
    • 설치하기: 커맨드로
    • 설치하기: 데스크톱 앱 화면에서
    • 업데이트
    • 이름은 바꾸지 않는다
    • Windows 사용자에게 배포할 때 주의
    • 설치할 수 있는 Mod 찾기

  10. 10장. Claude Code의 Mod는 안전한가 ― 샌드박스 없이 돌아가는 Mod를 설치 전에 가려내는 법

    Claude Code의 Mod는 샌드박스 없이 사용자 권한으로 돌아가는 코드입니다. 파일을 읽고 쓰고, 환경 변수(API 키 포함)를 읽고, 프로그램을 실행하고, 통신할 수 있습니다. 설치하기 전에 claude plugin validate로 Mod가 쓰는 API 목록을 뽑고,…

    읽기
    절 8개 보기
    • Mod가 닿는 범위
    • 왜 코드를 읽으면 알 수 있나
    • 1. claude plugin validate로 목록 뽑기
    • 2. API 4개를 쓰는 이유 확인하기
    • 3. 버전 고정하기
    • 4. 설치한 뒤에도 지켜본다
    • modscode의 13개 항목 심사
    • 정리

  11. 11장. 마치며 ― Claude Code의 Mods를 데스크톱 앱에서 계속 쓰려면

    이 책에서는 Claude Code의 Mods를 데스크톱 앱 Code 탭에서 쓰기 위한 최소 절차와, 자주 검색되는 문제의 답을 정리했습니다. 마지막으로 전체를 한 장에 요약합니다.

    읽기
    절 3개 보기
    • 한 장 요약
    • 버전이 올라가면
    • 더 깊이
Claude Code Mods 사용법Claude Code ModsClaude Code 데스크톱 앱Code 탭plugin.jsonhooks.jsonregister.tsxClaude Code 플러그인Claude Code 마켓플레이스전자책ebook

독자 평가

이 책 어땠나요?

별점과 함께 좋았던 점, 보완하면 좋을 점을 남겨 주세요. 저자가 모두 읽고, 골라서 답변과 함께 이 페이지에 싣습니다. 이름·연락처 같은 개인정보는 적지 마세요.

별점 (필수)

함께 읽으면 좋은 전자책

EBOOK 전체 보기 →