Claude Code mods: 세션 안에 컨텍스트 표시기 만들고 접근 권한 살펴보기

Claude Code 사용자는 플러그인으로 묶인 JavaScript 또는 TypeScript 함수를 이용해 어시스턴트 인터페이스와 동작을 바꿀 수 있게 됐다. Anthropic은 10월 1일 mods를 출시했다며 CLI와 Claude Desktop의 Code 탭에서 지원한다고 밝혔다. 개발자는 대화 안에 컨텍스트 사용량 표시기를 추가할 수 있다.

Anthropic에 따르면 mods는 사용자의 기기 권한으로 실행되며 샌드박스 처리되지 않는다. mod는 세션 데이터에 접근하거나 모델을 호출할 수도 있다. 설치하기 전에 코드와 게시자를 확인한다.

이 안내서는 Claude Code를 이미 사용하며 작고 눈에 보이는 사용자 지정을 원하는 개발자를 위한 것이다. 목표는 컨텍스트 창 사용량을 보여주는 표시기를 만들고, 생성된 플러그인을 살펴본 뒤 보관할지 결정하는 것이다. 안내는 Claude Code v2.1.287 이상을 기준으로 10월 2일 확인한 문서를 따른다. BIG CHANGE는 이 절차를 실행하거나 생성된 코드를 독립적으로 시험하지 않았다.

큰 변화

• 달라진 점: Claude Code mods는 어시스턴트 인터페이스 안에 표시 요소를 그리거나 이벤트를 바꿀 수 있는 함수를 추가하며, 기존 플러그인 시스템으로 묶어 배포한다.
• 왜 중요한가: 개발자는 표시기나 작업 흐름 제어 기능을 세션에 넣을 수 있지만, 해당 코드에는 컴퓨터와 대화에 대한 접근 권한도 주어진다.
• 앞으로 볼 점: mod의 실제 호출과 동작이 목적에 부합하는지, 어떤 조직 제어가 적용되는지, Claude Code 버전 간 API가 바뀌는지 확인해야 한다.

버전, 계정, 작업 공간 확인하기

셸에서 claude --version 명령을 실행한다. 현재 mods 문서는 최신 mods 안내에서 버전 2.1.287 이상이 필요하며 mods가 기본으로 활성화된다고 안내한다. 예전 얼리 액세스 환경 변수 설정은 이번 출시를 제어하지 않는다.

Claude Code 이용 권한과 신뢰할 수 있다고 승인한 작업 공간이 필요하다. Anthropic의 설정 안내에는 Pro, Max, Team, Enterprise, Console 계정 및 지원되는 타사 API 제공업체가 나와 있다. 무료 Claude 채팅 요금제에는 Claude Code가 포함되지 않는다. 조직 설정에 따라 사용자가 만든 mod를 불러오지 못할 수 있다.

대화형 터미널 세션을 사용한다. CLI와 지원되는 Desktop 세션에서는 mod 인터페이스가 표시된다. 훅은 VS Code 채팅 패널과 헤드리스 세션에서도 실행되지만 이 환경에서는 그림이 나타나지 않는다. Desktop의 WSL 세션은 플러그인을 지원하지 않는다.

표시기를 만들고 점검하기

Anthropic의 10월 1일 튜토리얼은 대화 차례가 끝난 뒤 컨텍스트 사용량을 읽어 표시하는 Token Weather를 설명한다. 비율은 마지막 응답에 사용된 컨텍스트와 모델의 컨텍스트 창을 기준으로 한다. 이는 사용량 표시기이지 답변 품질의 측정값은 아니다.

1. 신뢰된 작업 공간에서 claude 명령을 실행한다. 컨텍스트 비율, 사용 토큰 수, 컨텍스트 창 크기를 프롬프트 위에 표시하고 주 에이전트의 각 대화 차례가 끝난 뒤 갱신되는 mod를 만들어 달라고 요청한다. 문서에 나온 세션 사용량 API를 쓰고, 파일 접근·프로세스 실행·네트워크 요청·모델 호출이 없는 표시 전용 구현을 지정한다. 이는 문서상 생성 절차에 맞춘 우리의 더 제한적인 사양이다. 요청 문구 자체가 이런 제한을 강제하지는 않는다.
2. Claude가 만든 파일을 살펴본다. 생성 안내서는 플러그인을 세션 디렉터리의 다음 위치에 둔다: ~/.claude/dev-mods/ 매니페스트, 훅 설정, 코드를 검사한다. Claude Code는 핫 리로딩을 켤지 묻는다. 동의하면 이 세션의 mods와 이후 수정본이 실행된다.
3. 활성화하기 전에 claude plugin validate 명령을 실행하고 셸에서 실제 플러그인 디렉터리를 뒤에 붙인다. 보고된 이벤트 훅과 API 호출을 읽는다. 의도된 동작에는 사용량 읽기, 상태 관리, 렌더링이 필요하다. 파일, 환경 변수, 프로세스, 네트워크, 모델 접근을 조사하고 소스의 이벤트 재작성도 확인한다. 검증 성공은 로더와의 호환성을 뜻할 뿐 보안을 보장하지 않는다.
4. 검토한 구현을 승인한 뒤 /plugin 명령을 실행하고 Installed 탭에서 mod를 확인한다. 일반 요청을 한 번 보내고 차례가 끝난 뒤 표시 막대가 갱신되는지 살펴본다. 플러그인이 불러와지고 사용량 값이 눈에 보이며 갱신되는 것이 완료 신호다. 파일이 생성됐다는 사실만으로 작동이 입증되지는 않는다.

이 단계는 Claude가 첫 시도에서 의도한 구현을 만들 것이라고 보장하지 않는다. 전체 Token Weather 구현과 테스트 예시를 참고해 생성 결과를 비교할 수 있다. 튜토리얼은 일반 세션 사용량 조회는 무료라고 설명하지만 세부 내역을 요청하면 토큰 수 조회 요청이 전송될 수 있다. Claude에게 mod를 작성하거나 수정해 달라고 하는 작업에는 일반 Claude Code 사용량이 든다.

코드와 권한을 계속 살펴보기

세션에서 만든 mod는 임시 파일이다. 생성 안내서는 디렉터리를 원하는 위치로 복사해 보관한 뒤 세션을 시작할 때 claude --plugin-dir 옵션과 해당 위치를 지정하라고 안내한다. 매번 불러올 때마다 버전별 선언은 .claude-plugin/types/ 경로에 기록된다. API가 바뀔 수 있으므로 업데이트할 때 이 선언을 확인한다.

Anthropic의 관리 안내서는 도구 권한 규칙이 가릴 수 있는 제한을 설명한다. 기본 보안 가드는 Team 또는 Enterprise 사용자나 관리 설정이 있는 기기에서 불러온다. 기본 설정에서는 거부 규칙이 사용자가 mod로 승인한 Claude 도구 호출보다 우선한다. 하지만 이런 규칙은 mod 자체의 파일 시스템 또는 프로세스 API 호출을 제한하지 않는다. 관리자는 사용자가 설치한 mods를 차단하거나 mod의 호출에 정책을 적용할 수 있다.

Pluto Security의 9월 22일 사전 출시 조사에서는 정식 출시 전 구현을 시험하며 자격 증명 접근, 인터페이스 기만, 원격으로 바뀌는 코드를 보고했다. Pluto는 이런 확장 프로그램용 보안 소프트웨어를 판매하고 보고서는 일반 제공 전에 나왔다. 플러그인 소스와 내려받은 의존성을 살펴볼 근거로는 유용하지만 특정 조사 결과가 v2.1.287의 동작을 입증하지는 않는다. 출시 시점의 권한 세부 정보는 Anthropic의 현재 문서를 따른다.

플러그인 제어 메뉴에서 mod를 비활성화한다. --safe-mode 명령은 한 세션에서 설치된 mods와 다른 사용자 지정을 생략한다.

사용량과 비용

Anthropic의 출시 및 mods 안내서는 별도 mods 요금을 명시하지 않는다. Claude Code 비용 안내에 따르면 구독 이용은 요금제 한도에서 차감되고 Console 및 클라우드 제공업체 이용은 토큰 기준으로 청구된다. 모델을 호출하는 mod는 그 사용량을 소비할 수 있다. 로그인 방식에 따라 /usage와 청구 화면을 확인한다. 컨텍스트 비율은 청구 금액도 지출 한도도 아니다.

검토한 플러그인과 함께 Claude Code 버전을 기록한다. 명령 실행 권한을 추가하거나 도우미를 다운로드하면 코드가 할 수 있는 일이 바뀌므로 추가 검토가 필요하다.

출처 및 추가 읽을거리

• Anthropic, Claude Code mods 사용자 지정 (2026년 10월 1일): 출시 발표, 플러그인 패키징, 기기 접근 권한에 대한 명시적 경고. Anthropic은 Claude Code를 개발하고 판매한다.
• Mods overview (10월 2일 확인): 버전, 세션 환경, 호스트 권한, 검증, 비활성화 제어.
• Create a mod (10월 2일 확인): 생성, 승인, 핫 리로딩, 보관, 버전별 타입 선언. BIG CHANGE의 시험이 아니라 예상 동작을 문서화한다.
• Getting started with Claude Code mods (Addy Osmani, 10월 1일): Token Weather의 지표, 코드, 테스트 예시. Anthropic이 시연한 결과다.
• Manage mods for your organization (10월 2일 확인): 보안 가드의 적용 대상, 거부 규칙의 범위, 관리자 제어. 사용자가 만든 mods가 기기와 완전히 격리되지는 않는다.
• Advanced setup 및 Manage costs effectively (10월 2일 확인): 계정 요건, 인증 방식에 따른 청구, 사용량 추적. 검토한 출시 자료에는 별도 mods 요금이 명시되지 않았다.
• Pluto Security, Inside Claude Code Function Hooks (9월 22일): 연구자가 수행한 출시 전 시험과 그 한계. Pluto는 확장 프로그램 보안 제품을 판매하며 BIG CHANGE는 해당 시험을 재현하지 않았다.