Claude Code의 mod로 '사용량 게이지'와 'API 키 마스킹' 기능 구현하기 (단 3줄 명령어)

본문 소개

10월 1일, Claude Code에 'mod'라는 기능이 추가되었습니다. 이는 사용자가 직접 기능을 추가할 수 있는 시스템입니다.

설명만으로는 어떤 용도로 사용할지 파악하기 어려워, 제가 실제로 불편했던 두 가지 상황을 모드로 구현했습니다.

첫 번째는 사용량 제한(limit) 문제입니다. 작업 도중에 사용량이 한계에 도달하면 Claude가 멈춥니다. 현재 얼마나 남았는지는 일반 화면에는 표시되지 않습니다. 그래서 입력란 위에 사용량 게이지를 보여주는 mod를 만들었습니다. 사용량이 임박할 때는 Claude에게도 작업을 중단하도록 지시합니다.

두 번째는 API 키 문제입니다. .env 파일은 Claude가 읽지 않도록 설정할 수 있습니다. 그럼에도 불구하고, PATH를 확인하려는 목적으로 env 명령을 실행하게 하면 환경 변수에 저장된 키가 그대로 Claude에게 전달됩니다. 그래서 Claude가 읽기 전에 이 키를 가리는(masking) mod를 만들었습니다.

上限が92%のとき、Claudeが作業の区切り方を先に出した画面

사용량 게이지를 추가하고, 5시간 사용량을 임시로 92%로 표시한 화면입니다. 대규모 재작업을 요청하자, Claude는 수정하기 전에 분할 방식을 제안했습니다 (실제 Claude의 답변).

두 기능 모두 GitHub에 공개되어 있으며, Claude Code에서 명령어 3줄만 입력하면 적용할 수 있습니다. 유료 플랜으로 Claude Code를 사용하며 사용량 제한 때문에 작업이 중단된 적이 있거나, API 키가 Claude에게 전달되지 않았는지 궁금한 분들께 유용합니다.

개요

mod	불편했던 점	적용 시 변화 내용
limit-meter	얼마나 더 사용할 수 있는지 알지 못한 채, 사용량 제한으로 작업이 멈춤	5시간 단위와 주간 단위의 사용 비율 및 초기화 시간이 입력란 위에 표시됨. 사용량이 임박하면 알림이 뜨고, Claude도 작업을 중단함
secret-mask	`.env`를 읽지 않도록 설정해도, `env` 결과 등에 섞인 키는 AI에게 전송됨	Claude가 읽기 전에 키나 비밀번호를 `[MASKED]`로 대체함

구성

mod란 무엇인가
사용량 게이지 (limit-meter)
API 키 마스킹 (secret-mask)
적용 방법
제작 시 어려웠던 점
적용 전 주의사항

1. mod란 무엇인가

modはClaude Codeの「出来事」に割り込む

mod의 작동 원리 (작성자)

mod는 Claude Code의 동작이나 화면에 사용자가 직접 기능을 추가하는 작은 프로그램입니다. Claude Code는 명령 실행, Claude 답변 완료, 화면 그리기 등 '사건(event)'을 발생시키면서 움직입니다. mod는 이 사건에 가로채기(intercept)하여 그대로 통과시킬지, 수정해서 통과시킬지, 아니면 멈춰서 직접 답할지를 선택합니다.

이전의 '훅(hook)'과의 차이점은 사건을 수정할 수 있고, 화면에 표시를 추가할 수 있다는 점입니다. 이번 두 기능은 이 두 가지 포인트를 사용했습니다. 사용량 게이지는 화면에 표시를 추가하고, 마스킹은 Claude에게 전달되는 결과를 수정합니다.

사용 가능한 버전은 Claude Code 2.1.287 이상입니다. 시스템의 자세한 내용은 mod 공식 문서(영어)에서 확인할 수 있습니다.

2. 사용량 게이지 (limit-meter)

입력란 위에 남은 사용량을 표시하기

入力欄の上に、5時間枠と週の枠が出ている

실제 화면. 5시간 단위는 0%, 주간 단위는 17%이며, 각각의 초기화 시간도 표시됨

Claude 유료 플랜에는 5시간 간격 제한과 1주일 간격 제한이 있습니다. 게이지는 이 두 가지 사용 비율과 초기화 시간을 보여줍니다. 숫자는 Claude Code가 응답과 함께 받고 있는 값 그대로입니다.

사용 비율이 70%를 초과하면 노란색, 90%를 초과하면 빨간색으로 변합니다.

사용량이 임박하면 알림 주기

右上の知らせと、黄色になったメーター

5시간 단위가 임시로 85%로 설정되어 실행된 화면. 우상단에 알림이 표시됨

5시간 단위가 80%와 95%를 초과했을 때, 주간 단위가 90%를 초과했을 때 우상단에 알림을 표시합니다. 같은 단위의 동일 단계에서는 알림이 한 번만 발생합니다.

Claude에게도 작업을 중단하도록 지시하기

5시간 단위가 90%를 초과하면, 요청 사항 뒤에 다음 문장을 추가하여 Claude에게 전달합니다. 이 문장은 화면에는 표시되지 않습니다.

[limit-meter] 사용량 제한이 임박하고 있습니다 (5시간 단위는 92% 사용, 4:00에 초기화). 사용량이 한계에 도달하면 작업은 중간에 멈춥니다. 이 요청으로 두 개 이상의 파일을 수정해야 한다면, 수정하기 전에 분할 방식을 짧게 제안하고 사용자 답변을 기다려 주세요. 하나의 파일로 끝낼 수 있는 작업이라면 그대로 진행해도 무방합니다.

가장 처음 화면은 이 상태에서 “로그인 화면을 요즘 스타일로 완전히 다시 만들어줘”라고 요청했을 때의 모습입니다. Opus 5.5는 로그인 화면이 3개의 파일로 구성되어 있어, 전부 다시 만들려면 2개 이상을 수정하게 될 것이라고 설명했습니다. 그 후 작업을 3단계로 나누어 “먼저 1부터 시작해도 될까요? 아니면 상한선 리셋(4:00)을 기다렸다가 3개를 한 번에 진행할까요?”라고 물었습니다.

핵심 사항

같은 요청을 Haiku 4.5에 하면, 구분을 표시하지 않고 수정하기를 시작했습니다. 문장 하나가 미치는 영향은 모델마다 다릅니다.
상한선 숫자가 나오는 것은 Pro, Max, Team 등의 플랜으로 사용할 때만 해당됩니다. API 키로 사용할 때는 대신 그 세션의 요금을 보여줍니다.
상한선이 가까울 때 보이는 모습은
LIMIT_METER_DEMO=92,40 claude
처럼 비율을 넣어 실행하면 확인할 수 있습니다. 리셋 시간은 실제와 같습니다.

3. API 키 마스킹 (secret-mask)

먼저, .env를 읽지 못하게 설정하기

API 키를 보호하는 기본은 Claude가 .env 파일을 읽지 못하게 하는 것입니다. Claude Code의 설정 파일(.claude/settings.json)에 다음과 같이 작성합니다.

{
"permissions": {
"deny": ["Read(./.env)", "Read(./.env.*)"]
...
}

이 설정을 넣고 시도하자, Claude는 .env 파일을 읽을 수 없다고 했습니다. Read 도구를 사용하거나 cat으로 표시하려 해도 거부당했습니다.

그래도 키는 노출된다

.env를 읽지 못하게 설정해도, env 결과에서 키가 전달됨. secret-mask를 넣으면 [MASKED]가 됨

.env를 읽지 못하게 설정한 상태에서 env를 실행시켜 키의 줄을 복사하도록 한 화면. mod 없음(위)과 secret-mask를 넣었을 때(아래). 값은 기사를 위한 가짜입니다.

이 설정으로 멈추는 것은 파일을 읽는 경우입니다. PATH를 확인할 목적으로 env를 실행시키면, 환경 변수에 저장된 API 키도 함께 출력되어 그대로 Claude에게 전달되었습니다. Claude가 읽었다는 것은 그 값이 AI에게 전송되었다는 의미입니다.

secret-mask를 넣으면, Claude에 도달하기 전에 키가 [MASKED]로 대체됩니다. 명령어 결과 외에도 읽은 파일이나 첨부 파일도 대상입니다. MAX_TOKENS=4096과 같은 비밀이 아닌 설정은 그대로 남아 있습니다.

마스킹할 항목

종류	예시
형태로 알 수 있는 키	Anthropic, OpenAI, GitHub, AWS, Slack, Google, Stripe, JWT
이름이 비밀을 나타내는 설정	`DB_PASSWORD=...` , `

Claude Code를 재시작하면 로드됩니다. 하나만 넣어도 괜찮습니다. 중지하거나 제거할 때도 /plugin
에서 조작합니다.

5. 만들면서 걸렸던 부분

두 가지 모두 Claude Code에게 부탁해서 만들었습니다. 실제로 작동시켜 보고 나서야 알게 된 것이 네 가지 있습니다. 직접 mod를 만들 때 참고가 될 것 같습니다.

어려웠던 점	해결 방법
mod 안의 시계는 UTC로 움직여서 일본 시간으로 나오지 않음	`/etc/localtime`에서 현재 시간대를 읽어와, 그 시간에 `$` (mod에서 Claude Code를 조작하는 진입점)을 함수에 전달하면 검사에서 막힘
전달할 목적지 함수를 파일 상단에서 선언함
Claude에게 붙인 '구분 방식을 제안해 줘'가 Haiku 4.5에서는 효과가 없었음	'두 개 이상의 파일을 수정한다면'이라고 조건을 명확히 작성했습니다. 그래도 Haiku 4.5에는 효과가 없어, Opus 5.5에서 효과를 봤습니다
테스트용 도구로는 대화 기록에 남기 직전의 수정을 끝까지 재현할 수 없음	수정한 후의 내용만 확인하는 테스트로 변경함

mod 내부 내용을 확인하려면 claude plugin validate가 편리합니다. 끼어드는 사건과 호출되는 기능이 목록으로 나옵니다. 만들고 있는 동안 이것을 여러 번 실행했습니다.

6. 넣기 전에 주의할 점

mod는 격리되지 않고 Claude Code와 같은 권한으로 작동합니다. 파일 읽기/쓰기도, 네트워크 연결도 할 수 있습니다. 내용이 확인된 mod만 넣어주세요.

이번에 두 가지가 사용하는 것은 다음과 같습니다. 둘 다 네트워크에는 연결하지 않습니다.

mod	사용 항목
limit-meter	상한선 숫자, `/etc/localtime`, `date +%z` 실행 (시간을 현재 시간대로 출력하기 위함)
secret-mask	Claude에게 전달되기 전의 명령어 결과, 읽은 파일, 첨부

사용처 가이드라인

곤란한 상황	넣을 mod
상한선 때문에 작업 도중에 막힌 적이 있음	limit-meter
큰 작업을 부탁하기 전에 남은 상한선을 보고 싶음	limit-meter
`.env`를 Claude에게 읽히고 싶지 않음	mod가 아니라, 설정의 `permissions.deny`에 `Read(./.env)`를 넣기
`env`나 로그 결과를 Claude에게 보여주는 경우가 있음	secret-mask

참고 자료

Customize Claude Code with mods (개발사 블로그, 2026년 10월 1일)
mod 공식 문서 (영어)
공식 예제 mod (anthropics/claude-code-playground)
Claude Code가 상한에 도달해도 '깔끔하게'까지 계속 작동하게 된 방법 (이전에 작성한 글)

홍보: 상한에 도달하면 다른 AI로 계속하기

상한 미터로 남은 것이 보여도, 기다릴 수 없을 때가 있습니다. session-relay는 새로운 채팅창에 '계속'이라고 입력하는 것만으로 이전 대화를 이어받는 도구입니다. 이용 범위는 툴마다 다르기 때문에, Claude가 멈춰도 Codex로 계속할 수 있습니다.

설치 방법은 터미널에서 다음 두 줄입니다.

npm install -g @shoujiki-panman/session-relay
relay install

자세한 내용은 이전에 작성한 글에 정리되어 있습니다.