Claude Code mod: mod란 무엇이고, 우리가 모든 에이전트에 넣는 mod는 무엇인가

2026년 10월 1일, Claude Code 2.1.287이 한 줄짜리 changelog 항목과 함께 출시되었습니다. "Added Claude Mods". 나흘 뒤, AgentsRoom은 자신이 실행하는 Claude 에이전트에 우리의 mod(모드) 하나를 불러오기 시작했습니다.

이 글에서는 mod가 무엇인지, 기존 확장 지점으로는 못 하던 무엇을 할 수 있는지, mod를 어떻게 작성하고 불러오고 테스트하는지, 그리고 AgentsRoom이 시작하는 모든 Claude 에이전트에 mod를 넣으면서 배운 점을 설명합니다. Claude Code에 관한 사실은 Claude Code 2.1.318을 설치한 상태에서 2026년 11월 9일에 읽은 문서와 changelog에서 가져왔습니다.

짧은 답. mod는 hooks module을 가진 Claude Code 플러그인입니다. hooks module은 JavaScript 또는 TypeScript 파일로, 이벤트가 일어나면 Claude Code가 자기 프로세스 안에서 그 함수를 호출합니다. 함수는 이벤트를 통과시키거나, 바꾸거나, Claude Code 대신 응답할 수 있습니다. mod는 이렇게 패널을 그리고, 명령을 추가하고, 셸 명령을 실행 전에 멈춥니다.

mod란 무엇인가

Claude Code에는 원래 플러그인이 있었습니다. .claude-plugin/plugin.json에 매니페스트를 둔 폴더로, 스킬, 서브에이전트, settings hook, MCP 서버를 하나로 묶어 한 번에 설치되게 합니다. mod는 플러그인이 담을 수 있는 것이 하나 더 늘어난 것입니다. 플러그인의 hooks/hooks.json이 modules 키 아래에 코드 파일을 지정하면, Claude Code는 그 파일을 불러와 파일이 내보내는 register 함수를 호출합니다. 이때 그 플러그인을 mod라고 부릅니다.

register 안에서 on(event, hook)을 호출할 때마다 함수가 이벤트에 연결됩니다. 도구가 실행되기 전의 tool.call, 프롬프트를 보낼 때의 prompt.submit, session.start, 슬래시 명령을 위한 command.run, Claude Code가 화면의 일부를 그릴 때의 ui.render 등이 있습니다. 모든 hook은 세 가지를 받습니다.

• $: mod API입니다. $.ui, $.command, $.fs, $.process, $.http처럼 mod가 자기 코드 바깥에서 할 수 있는 모든 것입니다.
• e: 평범한 데이터로 된 이벤트입니다. 도구 호출이라면 도구 이름과 인자입니다.
• next: 이벤트를 다른 mod에 넘기고, 이어서 Claude Code 본래의 동작에 넘긴 뒤 결과를 돌려줍니다.

무슨 일이 일어날지는 hook이 next를 어떻게 다루느냐로 정해집니다. next(e)를 반환하면 관찰만 한 것입니다. e를 고친 사본으로 next를 호출하면 이벤트를 고쳐 쓴 것입니다. next를 호출하지 않고 자신의 결과를 반환하면 직접 응답한 것입니다. 도구는 실행되지 않거나, Claude Code 자체의 그리기는 일어나지 않습니다.

문서는 이 함수들도 hook이라고 부릅니다. settings.json에 쓰는 hook과는 다르며, Claude Code는 이제 그쪽을 settings hook이라고 부릅니다.

mod, settings hook, 스킬, MCP 서버

네 가지는 서로 겹치며, 그중 mod가 가장 무겁습니다. 일을 해내는 가장 가벼운 것을 고르세요.

플러그인 하나에 네 가지를 모두 담을 수 있으므로, mod는 함께 동작하는 스킬과 MCP 서버 옆에 나란히 배포할 수 있습니다.

mod의 세 파일

my-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.ts

plugin.json은 평소의 플러그인 매니페스트로 이름, 버전, 설명을 담습니다. hooks.json은 코드를 가리킵니다. { "modules": ["./register.ts"] }처럼 그 파일 기준의 상대 경로 하나를 씁니다. register.ts가 hooks module입니다. Claude Code는 번들러도 빌드 단계도 없이 .js와 .ts를 바로 불러오며, 허용되는 bare import는 타입과 몇 가지 헬퍼를 위한 claude-code 하나뿐입니다.

우리가 넣는 mod: 이 파일은 누가 바꿨나?

AgentsRoom은 같은 저장소에서 여러 코딩 에이전트를 실행하고, 변경사항 탭에서 어느 에이전트가 어느 파일을 바꿨는지 보여 줍니다. 덕분에 각 에이전트의 작업을 따로 리뷰하고 커밋할 수 있습니다. Claude의 Edit와 Write 도구로 쓴 파일은 쉬웠습니다. Claude Code가 settings hook으로 알려 주기 때문입니다. 셸 명령으로 쓴 파일은 그렇지 않았습니다. sed -i, heredoc, codemod, rm은 파일 도구를 전혀 거치지 않습니다.

mod 이전에는 추측했습니다. AgentsRoom은 에이전트의 세션 트랜스크립트를 읽어 각 Bash 명령이 언제 시작하고 끝났는지 알아낸 다음, 파일의 수정 시각을 그 시간 창과 맞춰 보았습니다. 대부분은 통했지만, 이름을 붙일 수 있는 세 가지 방식으로 실패했습니다.

• 삭제된 파일에는 수정 시각이 없으므로, 삭제는 한 번도 귀속되지 않았습니다.
• grep 같은 읽기 전용 명령도 시간 창을 열었고, 그동안 에이전트가 무엇이든 썼을 수 있었습니다.
• 트랜스크립트 형식에 의존했는데, Claude Code는 이 형식을 마음대로 바꿀 수 있습니다.

mod가 추측을 없앱니다. 우리의 agentsroom-changes mod는 두 셸 도구에 대해 tool.call을 hook합니다. 명령이 실행되기 직전에 저장소의 스냅샷(git status와, 변경된 각 경로의 크기와 수정 시각)을 찍고, 직후에 하나를 더 찍습니다. 달라진 경로가 그 명령이 바꾼 것이며, 삭제도 포함됩니다. mod는 이를 로컬 HTTP 엔드포인트로 AgentsRoom 데스크톱 앱에 보냅니다. Claude Code가 스스로 읽기 전용으로 표시한 호출은 아무것도 주장하지 않습니다.

아래는 줄인 hook입니다. 전체 파일은 177줄이며, 대부분은 스냅샷과 그 한도에 관한 코드입니다.

import type { Register } from 'claude-code';

const SHELL_TOOLS = new Set(['Bash', 'PowerShell']);

export const register: Register = (on) => {
  on('tool.call', async ($, e, next) => {
    if (!SHELL_TOOLS.has(e.tool)) return next(e);
    const ready = await prepare($).catch(() => null); // agent id, repo root, snapshot
    if (!ready) return next(e);                        // outside AgentsRoom: do nothing
    const callId = e.tool_use_id;
    post($, ready.agentId, { kind: 'start', callId });
    const ran = await next(e);                         // the command runs here
    const wroteNothing = ran.deny !== undefined || ran.isReadOnly === true;
    await reportEnd($, { ...ready, callId }, wroteNothing)
      .catch(() => post($, ready.agentId, { kind: 'end', callId, paths: [] }));
    return ran;                                        // Claude sees the normal result
  });
};

데스크톱 앱은 mod를 자기 폴더로 복사하고, 설치된 Claude Code가 2.1.287 이상일 때만 각 Claude 에이전트를 claude --plugin-dir <that folder>로 시작합니다. 이 mod는 2026년 10월 5일 AgentsRoom 1.201.0에 넣어 출시했습니다.

넣으면서 배운 점

mod 때문에 사용자의 도구 호출이 희생되어서는 안 됩니다. 우리 hook은 Claude가 실행하는 모든 셸 명령 앞에 서 있습니다. 예외를 던지거나 네트워크를 기다리면 Claude의 작업이 멈춥니다. 모든 단계를 보호하고, 데스크톱 앱으로 보내는 전송은 모두 보내고 잊는 방식이며, 우리가 받아들이는 대기는 git status 스냅샷 두 번뿐이고 각각 15초가 상한입니다. 전송 하나를 잃으면 귀속 하나를 잃을 뿐, 명령을 잃지는 않습니다.

원하지 않는 곳에서는 아무것도 하지 않습니다. mod는 AgentsRoom이 자기 에이전트에 설정하는 환경 변수를 읽습니다. 이 변수가 없으면, 예를 들어 누군가 폴더를 자기 환경에 복사한 경우, 모든 hook이 곧바로 next(e)로 넘어갑니다.

--plugin-dir로 불러온 폴더는 감시됩니다. 그 폴더의 파일이 바뀌면 Claude Code는 mod를 다시 불러오고, 다시 불러올 때마다 register가 다시 실행됩니다. 이 점이 설치 방식을 정했습니다. 데스크톱 앱은 내용이 바뀌었을 때만 mod 파일을 씁니다. 에이전트를 시작할 때마다 무조건 다시 쓰면, 이미 열려 있는 모든 Claude 콘솔에서 mod가 다시 불러와지기 때문입니다.

API가 바뀔 것에 대비하세요. 이벤트와 메서드는 릴리스마다 바뀔 수 있고, 문서도 직접 그렇게 말합니다. mod를 --plugin-dir에서 불러오면 Claude Code는 실행 중인 버전의 타입 선언을 .claude-plugin/types/에 씁니다. 우리는 웹 페이지가 아니라 이 선언을 기준으로 타입 검사를 합니다. 그리고 어떤 빌드가 우리 mod를 더는 불러오지 못해도 아무것도 깨지지 않습니다. mod가 준비 완료를 알리지 않으므로 AgentsRoom은 예전의 트랜스크립트 방식으로 돌아갑니다.

직접 만들기

들어가는 길은 두 가지입니다.

Claude에게 부탁하세요. 대화형 Claude Code 세션에서 원하는 mod를 설명합니다("프롬프트 위에 현재 git 브랜치를 보여 줘"). Claude는 기본 제공 스킬 plugin-authoring을 사용해 그 세션용 폴더에 mod를 쓰고, Claude Code는 Claude가 쓴 mod를 켤지 한 번 묻습니다. 그렇다고 답하면 그 턴이 끝날 때 mod가 불러와지고, 이후 mod를 바꾸는 턴이 끝날 때마다 다시 불러와집니다.

세 파일을 직접 작성한 뒤, 다음을 실행하세요.

claude --plugin-dir ./my-mod       # load it for one session, hot reload on save
claude plugin validate ./my-mod    # what Claude Code reads from it, without running it
claude plugin test                 # run the mod's *.test.ts files, no session needed

claude plugin validate는 모듈이 처리하는 이벤트를 담은 hooks: 줄과, 모듈이 호출하는 모든 mod API 메서드를 담은 calls: 줄을 출력합니다. 처리하려던 이벤트가 빠져 있다면 Claude Code도 그 hook을 호출하지 않습니다. 정적 분석에는 규칙이 있습니다. 호출은 매번 전부 쓰고($.ui.toast(...), 절대 const ui = $.ui가 아니라), 이벤트 이름은 문자열 리터럴로 넘기고, 자기 파일만 상대 경로로 import합니다.

mod를 공유하려면 플러그인으로 다루면 됩니다. 폴더를 보내거나, 마켓플레이스(.claude-plugin/marketplace.json이 있는 저장소)에 올리면 사람들이 /plugin install <name>@<marketplace>로 설치합니다.

지금 읽어 볼 수 있는 mod

• Claude Code 기본 제공: /plugin의 Installed 탭, Built-in 섹션에 있습니다. 그중 /diff 패널과 AGENTS.md를 프로젝트 지침으로 읽는 로더는 Anthropic이 anthropics/claude-code 저장소의 mods 폴더에 테스트와 함께 소스를 공개합니다. 역시 기본 제공이지만 켜기 전까지 꺼져 있는 것이 You should know로, 사용자나 Claude가 놓쳤을 수 있는 것을 짚어 주는 보조 에이전트입니다.
• Anthropic의 예제: claude-code-playground 저장소에 있습니다. 프롬프트 위에 그려지는 컨텍스트 윈도우 예측, 위험한 셸 명령을 붙잡아 두고 무엇이 바뀔지 보여 주는 가드, 마지막 턴의 편집을 단계별로 훑는 /replay 명령입니다.
• 우리 mod: 위에서 설명한 대로 인터페이스가 전혀 없고 tool.call hook 하나뿐인 mod입니다. 필요한 것이 패널이 아니라 데이터라면 따라 하기 좋은 형태입니다.

남의 mod를 설치하기 전에

mod는 샌드박스에 격리되지 않습니다. 사용자의 권한으로 실행됩니다. 파일을 읽고 쓰고, 환경 변수와 설정(API 키 포함)을 읽고, 프로그램을 시작하고, 네트워크 요청을 보내고, 모든 프롬프트와 도구 호출을 보고, 사용자에게 묻기 전에 도구 호출을 승인할 수 있습니다. Claude Code의 샌드박스를 켰더라도 그것이 감싸는 것은 Claude가 실행하는 Bash 명령이지, mod가 시작하는 프로세스가 아닙니다.

그러니 설치하기 전에 읽어 보세요. mod를 클론하고 폴더에 claude plugin validate를 실행합니다. hooks:와 calls: 줄을 보면 아무것도 실행하지 않고도 mod가 무엇을 듣고 무엇에 손을 뻗는지 알 수 있습니다. 프롬프트 위에 띠만 그리는 mod가 $.http나 $.process를 호출할 이유는 없습니다. 설치한 모든 mod를 멈추려면 세션 하나를 --safe-mode로 시작하거나, ~/.claude/settings.json에 "disableAllHooks": true를 설정하세요.

mod가 실행되는 곳

화면을 그리는 mod는 자신이 어디서 실행되는지 확인하고, 아무것도 그려지지 않는 곳에서는 텍스트로 대체해야 합니다.

AgentsRoom에서는

아무것도 설치할 필요가 없습니다. Claude Code 2.1.287부터 각 Claude 에이전트가 mod와 함께 시작하고, 변경사항 탭은 각 셸 명령이 만들고, 수정하고, 삭제한 파일을 그 일을 한 에이전트 옆에 보여 줍니다. 그보다 오래된 Claude Code에서는 AgentsRoom이 예전처럼 트랜스크립트에서 셸 쓰기를 맞춰 봅니다.

같은 아이디어는 가능한 다른 CLI에서도 동작합니다. oh-my-pi는 같은 약속을 지키는 확장을 받고, 다른 CLI는 예전 방식대로 셸 쓰기를 맞춰 봅니다. Claude Code가 각 단계에서 노출하는 것을 더 깊이 활용하고 싶다면, Claude Code hook 가이드에서 mod 곁에서 동작하는 settings hook을 다룹니다.

자주 묻는 질문

Claude Code에서 mod란 무엇인가요?

mod는 hooks module을 담은 Claude Code 플러그인입니다. hooks module은 JavaScript 또는 TypeScript 파일로, 도구 호출, 프롬프트 전송, 화면 일부 그리기 같은 일이 일어나면 Claude Code가 자기 프로세스 안에서 그 함수를 호출합니다. 각 함수는 이벤트를 그대로 통과시키거나, 바꾸거나, 직접 처리할 수 있습니다. 그래서 mod는 패널을 그리고, 명령을 추가하고, 위험한 셸 명령을 붙잡아 둘 수 있습니다.

mod를 쓰려면 어떤 Claude Code 버전이 필요한가요?

터미널에서는 Claude Code 2.1.287 이상이 필요합니다. 2026년 10월 1일에 출시되었고, changelog에는 "Added Claude Mods"라고 적혀 있습니다. Claude Desktop 앱의 Code 탭은 2.1.286부터 지원합니다. VS Code 확장에서는 hook이 실행되며, mod가 그리는 화면을 보려면 확장 2.1.299 이상이 필요합니다. 확인하려면 claude --version을 실행하세요.

mod와 Claude Code hook은 무엇이 다른가요?

settings.json에 쓰는 hook은 이벤트가 발생하면 Claude Code 바깥에서 셸 명령, HTTP 요청 또는 프롬프트를 실행합니다. mod의 hook은 Claude Code 안에서 실행되는 함수입니다. settings hook이 못 하는 일을 할 수 있습니다. 인터페이스에 그리기, Claude의 턴 없이 실행되는 슬래시 명령 추가, 도구 호출을 고쳐 쓰거나 도구를 실행하지 않고 응답하기, hook 사이에 상태 공유하기입니다.

Claude Code mod는 설치해도 안전한가요?

mod는 샌드박스에 격리되지 않습니다. 사용자의 권한으로 실행되어 파일과 환경 변수를 읽고, 프로그램을 시작하고, 네트워크 요청을 보내고, 도구 호출을 승인할 수 있습니다. 신뢰하는 작성자의 mod만 설치하고, 먼저 폴더에 claude plugin validate를 실행하세요. mod를 실행하지 않고도 mod가 hook하는 이벤트와 mod가 하는 호출을 보여 줍니다.

Claude Code mod 예제는 어디에서 볼 수 있나요?

Anthropic은 /diff 패널과 AGENTS.md 로더 같은 일부 기본 제공 mod의 소스를 anthropics/claude-code 저장소의 mods 폴더에, 예제 mod를 anthropics/claude-code-playground 저장소에 공개합니다. 이 글에서 설명하는 AgentsRoom의 mod는 네 번째 유형의 예제로, 인터페이스 없이 tool.call hook 하나만 있는 mod입니다.

mod를 끌 수 있나요?

네. /plugin의 Installed 탭에서 mod 하나를 비활성화하거나, --safe-mode로 세션 하나만 시작하거나, ~/.claude/settings.json에서 disableAllHooks를 true로 설정하면 설치한 모든 mod가 settings hook과 함께 멈춥니다. --safe-mode와 disableAllHooks는 기본 제공 mod를 계속 실행합니다. 기본 제공 mod는 /plugin에서 하나씩 끕니다.