Claude Code 모드 설치 방법

이 가이드는 Claude Code 모드 설치 방법을 Claude Code가 지원하는 세 가지 방식별로 설명합니다. 실행 중인 세션 안에서 한 줄로 설치하는 방법, 셸에서 명령 두 개로 설치하는 방법, 로컬 폴더에서 임시로 불러오는 방법입니다. 예시에서는 ClaudeMods 마켓플레이스(rotbit/claudemods-marketplace)와 cm-git-branch 모드를 사용하며, 원하는 모드의 이름으로 바꿔 쓰면 됩니다.

모드는 플러그인이므로 이미 알고 계신 플러그인 명령을 그대로 사용합니다. 이 사이트의 모든 모드 페이지에는 올바른 이름이 미리 채워진 설치 블록이 있습니다.

모드를 설치하기 전에 무엇이 필요한가요?#

먼저 버전을 확인하세요.

claude --version

터미널에서는 Claude Code 2.1.287 이상이 필요합니다. 데스크톱 앱은 2.1.286부터 모드를 실행합니다. 버전이 낮다면 진행하기 전에 Claude Code를 업데이트하세요. 이전 버전에서는 모드가 실행되지 않습니다.

회사에서 Claude Code를 관리하고 있다면 관리자가 승인된 목록에 있는 모드만 사용하도록 제한했을 수 있습니다. 회사에서 모드가 로드되지 않는다면 설정을 관리하는 담당자에게 문의하세요.

방법 1: Claude Code 안에서 한 줄로 설치하기#

어느 세션에서든 다음과 같이 입력합니다.

/plugin install cm-git-branch --marketplace rotbit/claudemods-marketplace

플러그인 이름은 @ 접미사 없이 단독으로 입력합니다. Claude Code는 아직 모르는 마켓플레이스라면 먼저 확인을 요청한 뒤 추가하고, 모드를 설치하여 현재 세션에 바로 로드합니다. 이 형식은 Claude Code 2.1.275 이상이 필요한데, 모드를 실행할 수 있는 버전이라면 이미 이 조건을 충족합니다.

/plugin install rotbit/claudemods-marketplace만 입력하면 작동하지 않는다는 점에 유의하세요. --marketplace가 없으면 인수는 plugin@marketplace 형식이어야 하며, 그렇지 않으면 "marketplace not found" 오류가 발생합니다.

방법 2: 셸에서 설치하기#

마켓플레이스를 한 번 추가한 다음, 그 마켓플레이스에서 원하는 만큼 모드를 설치합니다.

claude plugin marketplace add rotbit/claudemods-marketplace
claude plugin install cm-git-branch@claudemods

@ 뒤에 오는 텍스트는 저장소 이름이 아니라 marketplace.json에 정의된 마켓플레이스의 이름(claudemods)입니다. marketplace add 후에 표시되는 성공 메시지에서 사용할 이름을 알려 줍니다.

두 명령 모두 기본적으로 사용자 설정에 기록되므로 모든 프로젝트에서 모드를 사용할 수 있습니다. 저장소 단위로 공유하려면 --scope project를, 한 프로젝트에서 나만 사용하려면 --scope local을 사용하세요.

claude plugin install cm-git-branch@claudemods --scope project

이미 열려 있던 세션은 그 안에서 다음 명령을 실행하기 전까지 새 모드를 인식하지 못합니다.

/reload-plugins

클릭으로 진행하고 싶다면 세션 안에서 /plugin install cm-git-branch@claudemods를 입력하세요. 플러그인 메뉴에서 모드의 상세 화면이 열리고, 그곳에서 범위를 선택할 수 있습니다.

방법 3: 설치하지 않고 모드 사용해 보기#

저장소를 클론한 폴더나 직접 작성 중인 폴더처럼 로컬 폴더에 있는 모드를 사용해 보려면 한 세션에만 로드하세요.

claude --plugin-dir ./cm-git-branch

설정에는 아무것도 기록되지 않습니다. 모드는 cm-git-branch@inline이라는 ID를 받으며, 종료하면 사라집니다. --plugin-dir은 여러 번 지정할 수 있고, hooks 모듈의 변경 사항을 저장하면 다시 시작하지 않아도 다시 로드됩니다. 무엇이 로드되었는지 확인하려면 다음을 실행하세요.

claude --plugin-dir ./cm-git-branch plugin list

출력에는 모드의 버전과 로드 상태가 표시되는 "Session-only plugins" 섹션이 있습니다. 이 방식은 모드를 검토하는 가장 안전한 방법이기도 합니다. 먼저 claude plugin validate ./cm-git-branch를 실행하고 hooks: 줄과 calls: 줄을 읽어 보세요.

모드가 실행 중인지 어떻게 확인하나요?#

/plugin을 여세요. 탭 아래에 1 mod active · cm-git-branch처럼 흐린 글씨의 줄이 로드된 모드를 보여 줍니다. 셸에서는 claude plugin list로 설치된 플러그인과 각 플러그인의 활성화 여부를 확인할 수 있으며, 스크립트에서 사용하려면 --json을 추가하세요.

모드가 목록에 있는데도 아무것도 보이지 않는다면 어디에서 실행하고 있는지 확인하세요. 모드는 터미널과 데스크톱 앱의 Code 탭에서만 화면을 그립니다. VS Code 채팅 패널이나 claude -p에서는 hooks는 실행되지만 UI는 표시되지 않습니다.

모드는 어떻게 설정하나요?#

대부분의 모드는 기본값이 있는 옵션을 선언합니다. 설치 직후 Claude Code가 일부 userConfig 옵션이 아직 설정되지 않았다는 메시지를 출력할 수 있습니다. 이는 정상이며, 기본값이 적용됩니다.

옵션을 변경하려면 세션에서 /config를 열어 해당 모드의 항목을 찾거나 /plugin configure를 사용하세요. 모드는 새 값으로 다시 로드됩니다. 셸에서는 설치 시점에 옵션을 지정할 수 있습니다.

claude plugin install cm-git-branch@claudemods --config hideWhenClean=true

또는 나중에 문자열 값으로 이루어진 JSON 객체를 파이프로 전달할 수도 있습니다.

echo '{"intervalMs": "5000"}' | claude plugin configure cm-git-branch --values-stdin

지정하지 않은 옵션은 현재 값을 그대로 유지합니다. 플래그 없이 claude plugin configure cm-git-branch를 실행하면 모든 옵션과 그중 설정되지 않은 옵션이 출력됩니다. 각 모드 페이지의 "사용자 지정" 섹션에는 해당 모드의 옵션이 표로 정리되어 있습니다.

모드를 업데이트, 비활성화 또는 제거하려면 어떻게 하나요?#

마켓플레이스의 최신 버전으로 업데이트합니다.

claude plugin update cm-git-branch@claudemods

새 버전은 다음 세션에서, 또는 /reload-plugins를 실행하면 즉시 로드됩니다.

모드를 제거하지 않고 끄거나 다시 켜려면 다음을 실행합니다.

claude plugin disable cm-git-branch
claude plugin enable cm-git-branch

세션 안에서는 /plugin disable cm-git-branch가 같은 역할을 합니다. 모드를 user가 아닌 다른 범위에 설치했다면 -s project(또는 user, local)를 추가하세요.

완전히 제거하려면 다음을 실행합니다.

claude plugin uninstall cm-git-branch

모드의 데이터 디렉터리를 남겨 두려면 --keep-data를, 자동으로 설치되었지만 더 이상 필요 없는 의존성까지 제거하려면 --prune을 넘기세요. 캐시된 사본은 나중에 정리되며, 바로 정리하려면 claude plugin prune을 실행합니다.

한 세션 동안 모든 모드를 끄려면 claude --safe-mode로 Claude Code를 시작하세요. 계속 꺼 두려면 설정에 "disableAllHooks": true를 지정합니다.

모드가 로드되지 않을 때의 문제 해결#

다음 항목을 순서대로 확인하세요.

• 버전. claude --version이 2.1.287 이상이어야 합니다.
• 다시 로드. 셸에서 설치하거나 업데이트한 뒤에는 /reload-plugins를 실행하거나 새 세션을 시작하세요.
• 활성화. /plugin의 Installed 탭에서 모드가 활성화되어 있어야 합니다. 비활성화된 모드는 설치되어 있어도 로드되지 않습니다.
• 이름. claude plugin install에는 plugin@marketplace-name 형식이 필요합니다. 추가한 마켓플레이스의 이름은 claude plugin marketplace list로 확인할 수 있습니다.
• 실행 환경. VS Code 채팅, claude -p, Agent SDK에서 UI가 표시되지 않는 것은 정상 동작입니다.
• 정책. 관리형 설정에서 모드를 승인된 목록으로 제한하거나 --plugin-dir을 차단할 수 있습니다.
• 충돌. 상태 표시줄처럼 같은 위치에 출력하는 두 모드는 서로를 가릴 수 있습니다. 하나씩 비활성화해 원인을 찾아보세요.

그래도 모드가 제대로 작동하지 않는다면 해당 모드 페이지에서 알려진 문제를 확인하거나, Claude Code 버전과 모드 폴더에 대해 실행한 claude plugin validate의 출력을 첨부해 문제를 보고하세요. 전체 명령 참조는 플러그인 CLI 문서에 있습니다. 모드가 처음이라면 Claude Code 모드란 무엇인지부터 읽어 보고, 디렉터리에서 하나를 골라 보세요.