클로드코드 모드가 뭔가요? Claude Code Mods로 화면과 동작 바꾸는 법 2026 기준 정리

클로드코드 모드가 뭔가요? Claude Code Mods로 화면과 동작 바꾸는 법 2026 기준 정리

클로드코드 모드가 뭐길래 다들 이야기하나요?

클로드코드 모드(Claude Code Mods) 기능이 공개됐습니다. Claude Code v2.1.287부터 클로드코드 플러그인이 화면을 그리고 동작까지 바꿀 수 있어요. GitHub 릴리스는 2026-10-01 18:00(UTC)에 올라왔고, 한국시간으로는 2026-10-02 새벽 3시입니다. 릴리스 노트 첫 줄은 "Added Claude Mods: plugins may now modify deeper behavior"입니다.

처음 들으면 질문 두 개가 바로 떠오르죠. "코딩을 못 하는데 나도 써 볼 수 있나요?" 그다음에는 "내 컴퓨터를 건드리는 기능인데 안전한가요?" 둘 다 당연한 걱정이에요.

이 글에서는 모드가 무엇인지, 화면이 어디서 보이는지, 공개 샘플에는 무엇이 있는지 차례로 짚습니다. 말로 요청해 만드는 순서와 켜고 끄는 방법, 설치 전 보안 확인도 다룹니다. 직접 설치해 돌려 본 후기는 아니에요. 공식 문서와 GitHub 원문을 읽고 정리한 글입니다.

모드는 정확히 무엇이고 기존 훅과 뭐가 다른가요?

Anthropic 공식 문서는 모드를 이렇게 정의합니다. "A mod is a plugin that changes how Claude Code looks and behaves." Claude Code의 모양과 동작을 바꾸는 플러그인이라는 뜻이에요. 내용물은 JavaScript나 TypeScript로 쓴 이벤트 핸들러입니다. 이벤트 핸들러는 "도구를 호출했다", "프롬프트를 제출했다" 같은 일이 생길 때 불려 나오는 작은 함수예요.

핸들러는 이벤트를 3개 방식 중 하나로 다룹니다. 지켜보기(Observe), 바꾸기(Rewrite), 대신 처리하기(Answer)예요.

비유하면 설정 훅(settings hook, 설정 파일에 적는 셸 명령이나 HTTP 요청 형태의 기능)은 건물 밖에서 문을 두드리는 경비원입니다. 모드는 건물 안 배선반에 직접 손을 대는 전기 기사예요. 할 수 있는 일이 커진 만큼 출입증 관리도 중요해집니다. 공식 문서에 따르면 설정 훅·스킬·MCP는 Claude Code 바깥에서 스크립트를 돌리거나 텍스트·도구를 건네는 방식이고, 모드는 안에서 돌기 때문에 패널을 새로 그리거나 원래 화면을 다시 그리는 일까지 할 수 있어요.

모드(Mods)란?: Claude Code 프로세스 안에서 돌아가며 화면과 동작을 바꾸는 플러그인입니다. JavaScript 또는 TypeScript 이벤트 핸들러로 만들고, 이벤트를 지켜보거나 바꾸거나 대신 처리해요. Claude Code v2.1.287 이상에서 기본으로 켜져 있습니다.

공식 문서의 "What a mod can do" 항목을 5가지로 묶으면 다음과 같아요.

한 가지 선이 있어요. 권한 확인 프롬프트(permission prompt)는 모드가 모양을 바꿀 수 없고 내용도 건드릴 수 없습니다. Claude Code에는 /diff 패널, AGENTS.md 로딩, 텔레메트리 같은 내장 모드 6개가 이미 들어 있기도 해요.

화면은 어디에서 보이나요? 터미널과 VS Code는 다른가요?

화면이 보이는 곳은 터미널과 데스크톱 앱 Code 탭입니다. 공식 문서의 "Where mods run" 표에는 7개 환경이 나와 있어요.

화면은 어디에서 보이나요? 터미널과 VS Code는 다른가요?

이미지 출처: github.com

VS Code 채팅 패널과 claude -p는 모드 코드가 돌긴 하지만 패널이나 띠 같은 화면은 보이지 않아요. 화면을 그리는 모드를 체험하려면 터미널이나 Code 탭에서 여는 편이 맞습니다.

최소 버전은 v2.1.287이에요. GitHub에는 v2.1.289(2026-10-03 게시)도 올라와 있고, 문서가 요구하는 기준은 "v2.1.287 이상"입니다.

공개 샘플은 뭐가 있나요? 3종과 커뮤니티 확장 1종

Anthropic은 claude-code-playground 저장소(커밋 569c528, 2026-10-01 반영)에 샘플 모드 3종을 공개했습니다. 먼저 알아 둘 점이 있어요. 샘플은 Claude Code에 기본 포함되지 않아서, 저장소를 내려받아 --plugin-dir로 한 세션만 불러오거나 로컬 마켓플레이스로 추가해야 합니다. 각 README도 "Not an official Anthropic product; no support or maintenance is implied."라고 밝혀요. 공식 제품이 아니고 지원도 없다는 뜻입니다.

Blast Radius의 README는 스스로 이렇게 선을 긋습니다. "This is a safety net, not a permission system." 안전망이지 권한 시스템이 아니라는 말이에요. $(...), alias, eval, bash -c, xargs rm, find -delete 같은 형태는 못 잡는다고도 적혀 있어서 안전을 책임져 주는 도구로 읽으면 안 됩니다. Replay Theater도 전체 백업이나 되돌리기 기능은 아니에요.

커뮤니티 확장도 하나 있습니다. Eric Cologni(X @facilabo)가 올린 token-weather-usage(저장소 augiefra/claude-mods)예요. 프롬프트 위 한 줄에 5시간·주간 한도 사용률과 컨텍스트 날씨를 보여 줍니다. 저장소는 2026-10-02에 생성됐고 GitHub 별은 3개(2026-10-04 조회)예요. Anthropic 공식 제품이 아니라 개인 공개 확장입니다. README는 네트워크 요청이 없고 세션별 컨텍스트 측정값은 8일 미사용 시 삭제된다고 밝히면서도 "read it before installing"이라고 권해요. 모드는 Claude Code와 같은 권한으로 도는 코드이니, 설치 전에 그 코드(파일 1개)를 직접 읽어 보라는 얘기죠.

모드는 어떻게 만드나요? 코딩 없이 말로 요청해도 되나요?

모드 만드는 법은 생각보다 단순하고, 코딩을 몰라도 여기까지는 됩니다. Claude Code 대화형 세션에서 원하는 모드를 말로 설명하면, Claude가 내장 plugin-authoring 스킬로 작성해 줘요. 공식 제작 가이드(create.md)가 안내하는 순서는 4단계입니다.

1. 대화형 세션에서 모드를 말로 설명합니다. 예를 들어 make a mod that shows the current git branch above the prompt(프롬프트 위에 현재 git 브랜치를 보여 주는 모드를 만들어 줘)처럼요. Claude는 ~/.claude/dev-mods/<세션ID>/에 모드를 씁니다. default·acceptEdits 권한 모드에서는 파일마다 생성 승인을 물어요.
2. 첫 파일을 저장할 때 hot reload(바뀐 내용을 다시 불러오기, Claude가 쓴 모드는 턴이 끝날 때 반영) 여부를 묻습니다. 만들어진 내용을 확인한 뒤 Enable for this session을 고르면 턴이 끝날 때 로드돼요. Not now를 고르면 그 세션을 다시 시작할 때 로드됩니다.
3. /plugin을 실행하고 Tab으로 Installed 탭에 가서 모드가 보이는지 확인해요. 여기서 끌 수도 있습니다.
4. 원하는 대로 안 되면 Claude에게 고쳐 달라고 요청합니다.

2번의 "내용 확인"을 건너뛰지 마세요. Claude가 쓴 코드도 결국 내 권한으로 돌아갑니다.

Claude가 만든 모드는 그 세션에서만 로드돼요. 세션 모드 폴더는 cleanupPeriodDays가 지나면 삭제됩니다. 계속 쓰려면 폴더를 다른 곳에 복사해 claude --plugin-dir ~/mods/<이름>으로 띄우거나 마켓플레이스에 올려야 합니다. 일반 Claude 웹 채팅이 아니라 Claude Code 세션에서 요청해야 하는 점도 기억해 두세요. claude -p나 dontAsk 모드처럼 승인할 사람이 없는 세션, 신뢰 확인을 안 한 작업 폴더, --safe-mode·--bare·disableAllHooks 상태에서는 Claude가 쓴 모드가 로드되지 않아요.

직접 작성하면 파일은 3개

튜토리얼의 구조는 짧습니다.

first-mod/
├── .claude-plugin/
│   └── plugin.json      (플러그인 매니페스트)
└── hooks/
    ├── hooks.json       ("modules": ["./register.js"]로 코드 위치 지정)
    └── register.js      (register(on)을 export)

hooks.json에 modules 키가 있어야 모드로 인식돼요. register(on) 안에서 on('tool.call', ...)처럼 이벤트별 핸들러를 등록하고, 각 핸들러는 $(mods API), e(이벤트), next(다음 처리기) 세 인자를 받습니다. claude --plugin-dir ./first-mod로 실행하면 폴더를 감시해 저장할 때마다 다시 불러와요. Node.js, 번들러, 빌드 단계는 필요 없습니다. 검사는 claude plugin validate ./first-mod, 테스트는 claude plugin test예요. 이름이 claude-로 시작해 Anthropic 공식처럼 보이면 validate가 실패합니다.

켜고 끄는 법

공식 문서의 "Turn mods on or off" 기준으로 범위는 3가지입니다.

disableAllHooks, --bare, --safe-mode는 내장 모드까지 멈추지는 않아요.

설치 전에 뭘 확인해야 하나요? 모드는 샌드박스가 아니라고요

모드는 샌드박스(프로그램을 격리된 울타리 안에서만 돌리는 장치)가 아닙니다. 공식 문서는 이렇게 적어요. "A mod is code that runs with your permissions. It can read and write your files, start processes, and make network requests. Install mods only from authors and marketplaces you trust." 사용자 권한으로 실행되는 코드이니 신뢰하는 작성자와 마켓플레이스의 모드만 설치하라는 뜻입니다. 같은 날 @ClaudeDevs 공식 계정도 후속 글로 같은 당부를 올렸어요.

공식 문서의 "What a mod can reach"에 나온 범위는 6가지입니다.

• 내 계정이 접근할 수 있는 파일 읽기·쓰기, 프로그램 실행, 네트워크 요청
• 환경변수와 설정 파일에 보관한 API 키 읽기
• 내가 보내는 모든 프롬프트와 Claude의 모든 도구 호출 열람
• 프롬프트·도구 호출 재작성, 다른 세션에 메시지 보내기
• 사용자에게 묻기 전에 도구 호출 승인
• 내 요금제나 API 키로 모델 호출(사용량 소모)

문서는 "Mods aren't sandboxed."라고 못 박습니다. Claude Code의 샌드박스 기능을 켜도 그 격리는 Claude가 실행하는 Bash 명령에만 적용돼요. 모드가 시작한 프로세스는 샌드박스 밖에서 돕니다. 도구 호출을 승인하는 모드는 ask 규칙이 물어야 할 호출이나 내 PreToolUse 훅이 막은 호출도 승인할 수 있어요. claude.dev 가이드에는 모드가 "a sandbox of its own"에서 돈다는 문장이 있지만, DOM과 Node가 없는 실행 공간이라는 구조 설명이지 보안 격리를 뜻하지 않습니다.

설치 전 점검 도구는 claude plugin validate예요.

claude plugin validate ./some-mod

모드 코드를 실행하지 않고 정적 분석으로 출력의 hooks: 줄(처리하는 이벤트)과 calls: 줄(요청하는 작업)을 보여 줍니다. 환경변수를 읽거나 쓰면 env reads:, env writes: 줄도 나와요. 모드는 mods API를 거치지 않고는 바깥 작업을 할 수 없어서 이런 사전 목록화가 가능하다고 문서는 설명합니다.

조직 단위 통제도 있어요. 공식 문서에 따르면 관리자는 managed settings의 allowManagedModsOnly 등으로 사용자가 설치한 모드의 로딩을 제한할 수 있습니다. 이때 플러그인은 설치된 채로 남고 모드만 멈춰요.

마무리

클로드코드 모드는 Claude Code v2.1.287부터 화면과 동작을 바꾸게 해 주는 플러그인입니다. 말로 요청하면 만들어 주지만, 그 세션에서만 쓰이고 내 권한으로 돌아가요. 공개 샘플 3종은 기본 포함이 아니고 각자 한계가 분명하니, 쓰기 전에 README의 "알아둘 점"부터 읽는 쪽이 낫습니다. 설치 전에는 출처를 확인하고 claude plugin validate 결과를 눈으로 보세요. 마음에 안 들면 claude --safe-mode로 한 세션만 모드 없이 시작해 볼 수 있습니다.

자주 묻는 질문

샌드박스를 켜 두면 모드도 막히나요?

아니요, 막히지 않습니다. 공식 문서(overview.md)는 샌드박스 격리가 Claude가 실행하는 Bash 명령에만 적용되고 모드가 시작한 프로세스는 샌드박스 밖에서 돈다고 설명해요. 그래서 샌드박스 설정과 상관없이 신뢰하는 출처의 모드만 설치해야 합니다.

모드 때문에 Claude Code가 이상해지면 어떻게 끄나요?

한 세션만 끄려면 claude --safe-mode로 시작하면 됩니다. 모드 하나만 끄려면 /plugin의 Installed 탭에서 비활성화하거나 제거하고, 모든 세션에서 끄려면 ~/.claude/settings.json에 "disableAllHooks": true를 넣어요. 공식 문서의 "Turn mods on or off" 3가지 방법이고, 내장 모드는 이 방법으로 멈추지 않습니다.

코딩을 전혀 모르면 모드를 못 만드나요?

만들 수 있어요. 대화형 세션에서 원하는 모드를 말로 설명하면 Claude가 plugin-authoring 스킬로 작성합니다(공식 제작 가이드 create.md). 다만 Enable for this session을 누르기 전에 만들어진 내용을 확인해야 하고, 그 모드는 해당 세션에서만 로드돼요.

참고 자료

• Claude Code Mods 개요 (공식 문서)
• Claude Code 모드 만들기 (공식 문서)
• Claude Code v2.1.287 릴리스 (GitHub)
• Claude Code Mods (Claude 공식 블로그)
• Getting started with Claude Code mods (claude.dev)
• claude-code-playground 샘플 모드 3종 (GitHub)
• token-weather-usage 커뮤니티 확장 (GitHub)
• @ClaudeDevs 공식 발표 (X)